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Preface 


intended Audience 


This manual is written for the full range of VAX/VMS system users, from 
beginners to the most advanced level: system operator, applications pro- 
grammer, system manager, or software developer. Emphasis is on the how to 
use information, and detailed descriptions of SORT internals are kept to a 
minimum. 


You can use SORT as an interactive utility (Chapter 2), or as a set of 
subroutines, callable from VAX-11 programming languages (Chapter 3). 


New users or those with simple sort requirements, can learn how to use SORT 
by reading Chapters 1 and 2. To use SORT efficiently or for more than simple 
sorts, read also Chapters 3 and 5. 


VII 


Structure of this Document 


Chapter 1 introduces the VAX-11 SORT program and describes its environ- 
ment, features, and requirements, and explains user requisites. 


Chapter 2 explains how the SORT command is used to run VAX-11 SORT 
interactively or in batch mode. 


Chapter 3 explains how to call SORT routines from user programs, and de- 
scribes how to use subroutine parameters. 


Chapter 4 provides complete lists of SORT error messages and recovery proce- 
dures. 


Chapter 5 provides information and programming techniques for improving 
VAX-11 SORT efficiency. 


The Glossary defines terms used in this manual. 


Appendixes A, B and C consist of helpful programming aids such as: code 
conversion charts, character sets, and data types used by VAX-11 SORT. 


Appendix D summarizes basic concepts. 


Finally, page references to key terms appear in the index. 


Associated Documents 


VILL 


The following documents are relevant to VAX-11 SORT users: 


e PDP-11 SORT Reference Manual 

¢ VAX/VMS Primer 

e VAX/VMS Summary Description 

e VAX/VMS Command Language User’s Guide 

e VAX/VMS System Messages and Recovery Procedures Manual 
¢ Introduction to VAX-11 Record Management Service 

¢ VAX-11 Record Management Services User’s Guide 

e VAX-11 Record Management Services Reference Manual 

e VAX-11 Software Installation Guide 

e VAX/VMS System Services Reference Manual 

¢ VAX-11 Common Run-Time Procedure Library Reference Manual 
e VAX~-11/780 Architecture Handbook 

e VAX-11/780 Processor Handbook 

e VAX-11/780 Software Handbook 

¢ VAX-11/780 Technical Summary 


Symbology 


You will encounter the following symbols, colors, and special graphics in this 


manual. 
dollar sign 


$ 


Return 
RET 


Square Brackets 
() 


Braces 


i 


n 


Underscore 


Hyphen 


Comma 


Circumflex 


Uppercase Letters 
| ABC 


Lowercase Letters 
abc 


Red print 


Shading 


The system prompt; indicates that the VAX/VMS com- 
mand interpreter is ready for command input. The next 
$ prompt indicates successful completion of command 
processing, and the system’s readiness to accept an- 
other command. | 


In addition, the $ must appear in the first character 
position of a command to be executed in an indirect 
command file. 


Indicates RETURN or ESC key entry required. Press- 
ing this key after entering a full command line ends the 
command input and begins processing. 


When using the prompted command format, or €S0) 
is required after each command segment. 


Used in manual text to indicate qualifiers; not entered. 
Used in command syntax to indicate enclosed portion is 
optional. 


Used in manual text to indicate input options where 
one in the vertical list must be selected; not entered. 


Used in this manual text to indicate variable data input 
(typically some number value); not entered. 


Indicates an entered underscore character. 
Indicates line continuation. 


Commas are entered to separate listed subqualifiers. 


Represents the CTRL key on many terminals. Nor- 
mally entered simultaneously with the alphabetic char- 
acter that immediately follows. 


For example, “C is the same as CTRL/C. 


Indicates command inputs that must be entered as 
shown. 


Used in text to describe the command syntax; not 
entered. 


Indicates characters you type at the terminal. All sys- 
tem printouts appear in black print. 


Used to highlight that portion of an example that is 
being described in text. 


Chapter 1 
Introduction 


VAX-11 SORT rearranges and reformats records in any VAX-11 record man- 
agement service (VAX-11 RMS) file organization. SORT consists of two func- 
tional parts: a control program called the utility, and a callable subroutine 
package. The utility can be used in an interactive terminal session or in batch 
mode using the VAX/VMS DIGITAL command language (DCL) SORT com- 
mand. The callable subroutines are invoked by the SORT utility. Users can 
write control programs in most VAX-11 languages using these callable 
subroutines. 


You can invoke SORT interactively by entering a SORT command with quali- 
fiers and input/output parameters. The command specifies one of four sort 
types and the sorting keys. During program execution, SORT indicates all 
errors. At the completion of each session, SORT prints a statistical summary. 


1.1 Sort Types 
The four sort types (or sorting processes) are: 


e Record Sort 
e Tag Sort 
e Address Sort 


e Index Sort 


Record Sort produces a reordered data file sorted by specified key fields (that 
is, entire records are reordered). This sort uses any VAX/VMS input device 
and can process any valid VAX-11 RMS format. Record, a relatively slow 
sort, is the default process. 


Tag Sort produces the same kind of output file as record sort by sorting only 
the record keys. Tag sort then randomly reaccesses the input file to create a 
resequenced output file according to those record keys. This method conserves 
temporary storage, but can only accept input files residing on disk. 


Address Sort produces an address file. That is, a reordered address file, on 
disk only, of record’s file addresses (RFAs). The address file, sorted by record 
keys, can be used by programs as an index to read the original file in the 
desired sequence. This is the fastest of the four sorting processes. 


index Sort produces an address file containing the key field of each data record 
and a pointer (RFA) to its location in the input file. The address file can be 
used by programs to randomly access data from the original file in the desired 
sequence. Like address sort, this is a high-speed process. 


For more information on sort types, see Chapter 2. 


1.2 Input and Output 


As input, SORT accepts sequential, relative or indexed-sequential data files 
containing records of fixed, variable, or variable with fixed-length control 
(VFC) format. Character, binary, or decimal data types, and files from disk, 
magnetic tape, card reader or terminals are accepted. 


As output, SORT produces sequential, relative or indexed-sequential data 
files. These files can be of fixed, variable or VFC format and output to disk, 
magnetic tape, printer or terminal. In addition, SORT outputs address files 
(on disk only) for sequential access by programs. 


1.3 Statistics 


SORT prints statistics at the end of each session. These statistics include: 


e Elapsed execution time 


e Number of records read, sorted, and output 


e The longest record length 


For more information on statistics and how they can be useful, see Section 
2.2.3 and Chapter 5. 


1.4 Functions Supported by VAX-11 SORT 
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1. Sort types: record, tag, address, index. 


2. File organizations as input and output: sequential, relative, indexed- 
sequential. All VAX-11 RMS file types are supported. 


3. Record format for input and output: fixed, variable, and VFC. All 
VAX-11 RMS record formats are supported. . 


4, All VAX/VMS devices are supported for input and output. 


5. Multivolume support as provided by VAX-11 RMS. 
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10. 


11 


Callable subroutine package. VAX-11 programming languages producing 
native mode code are supported. Included are: 


VAX-11 COBOL-74 

VAX-11 FORTRAN IV-PLUS 

VAX-11 MACRO 

VAX~-11 BLISS 

Controlled by command string or specification file. 
Free field and fixed position specification file formats. 
Data Types: 

e Character data is ASCII representation 

e Binary data is VAX representation 

e Packed decimal data is VAX representation 

e Zoned data is VAX representation 

e Decimal data supports: 


— leading separate sign 
-—— leading overpunched sign 
— trailing separate sign 
— trailing overpunched sign 


Ascending/descending output based on each key field. 


. Output file blocking and allocation size. 
12. 
13. 
14. 


Sort statistics provided at completion. 
ASCII collating sequence for character keys. 


RSX SORT-11 utility option. 
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Chapter 2 
Running SORT in Interactive and Batch Mode 


This Chapter explains how to use the SORT command to sort files interac- 
tively or in batch mode. 


2.1 The SORT Command 


The SORT command consists of three parts: the command name, the input 
file specification parameter, and the output file specification parameter, in 
that order. Each part must be separated by one or more spaces or tabs, and is 
invoked by terminating with when the command is entered as a continu- 
ous command string. 


This section describes how sorts are performed using the SORT command 
without the specification file qualifier. The specification file is a more sophis- 
ticated method of controlling SORT, and therefore is described later in Sec- 
tion 2.5. The specification file is a command qualifier and should not be 
confused with the file specifications for the input and output files. 


Format: 
Per oeerrr Tr ile spas T aTTan OTT 
¢40RTCaualifiers NAneput-file-specificationlaualifiers 


woutbPut-file-~specificationlCaualifiers] (GED 
3) 
@ Command Name (SORT) 


SORT is the command name that invokes the VAX-11 SORT utility. Com- 
mand name qualifiers specify the sort process, describe the sorting key(s), 
specify the number of work files, indicate the specification file if a sort other 
than a standard sort is to be performed, and finally indicate whether the 
VAX-11 SORT utility or the RSX SORT-11 utility is to be invoked. 


® input File Specification Parameter 


This parameter specifies the physical location of the input file (see Appendix 
D for additional file specification information). Input file qualifiers define the 
input file attributes such as record format and file size. 


© Output File Specification Parameter 


This parameter specifies the physical location of the sorted output file (see 
Appendix D for additional file specification information). 


Output file qualifiers define the output file attributes such as record format, 
record size, block size, file organization, allocation quantity, contiguous allo- 
cation, overlay existing fle, and bucket size. 


The VAX/VMS command interpreter will prompt you for input and output 
file specifications if they are not entered in the first command string. The 
following is an example of prompted format: 






$ »SIZE=80) ~“@—— command with qualifiers 
$ File: R100SQ @eD input-file-specification 
$_ Output: TEST.TMP output-file-specification 


The following example shows how the SORT command is structured: 


SORT Command 





Command 
Name . Command Parameters 





$ Keyword input-file-spec output-file-spec RED 


Command Qualifiers File Qualifiers 
(/keyword/keyword/keyword) (/keyword/keyword/keyword) 





Subqualifiers 
(=n) or (=(keyword,keyword)) 


Values 


(=n) 


Notes: 1. keywords may be truncated and are unique. 
2. n indicates variable data input (typically some number value). 


Table 2-1 summarizes all the SORT command qualifiers, subqualifiers, and 
input values. The complete details on qualifiers and input values are dis- 
cussed in Section 2.4. 
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Table 2-1: SORT Command Summary 


Notation Used: 


e Underlined upper-case characters indicates the minimum entry required. 

e Brackets [ ] indicate enclosed portion is optional. 

e If several enclosed words are listed vertically, only one may be used. 

© Qualifiers, subqualifiers and values that must be specified are shown without brackets. 
e Braces { } indicate a selection must be made from the vertical list. 

e Defaults are shown in bold type. 


Command Subqualifiers 
Qualifiers and Values Notes 
$ SORT 
RECORD 
/PROCESS= TAG 
ADDRESS 
INDEX 
/KEY= ( [ NUMBER=11-10}] /KEY: is not required if specified in a spec- 


ification file. 


POSITION=(1-163831 


1-255 for CHARACTER data type 
»IZE=<1, 2, or 4 for BINARY data type 
1-31 for DECIMAL data type 


,CHARACTER 

BINARY 

LONED 

,\DECIMAL 

,PACKED__DECIMAL 

JLEADING_SIGN TRAILING__SIGN is default if data type 
» TRAILING__SIGN is DECIMAL. 

EPARATE__SIGN OVERPUNCHED_SIGN is default if 
,OVERPUNCHED__SIGN data type is DECIMAL. 


ASCENDING) 
,DESCENDING) 


[/WORK_FILES=(0,2-10)] 
[ /SPECIFICATIONI=file-specification]] SYS$INPUT is default file name. 


[/Rsx11] | VAX-11 SORT is default. /RSX11 requires 
PDP-11 SORT command switches. Refer 
to the PDP-11 SORT Reference Manual. 


(continued on next page) 
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Table 2-1: SORT Command Summary (continued) 


Input File Subqualifiers 
Qualifiers and Values 


input-file-specification 


[/FORMAT= — (RECORD_SIZE=(1-16383]] 


[ FILE_SIZE=[1-4294967295)) ] 


Output File Subqualifiers 
Qualifiers and Values 


output-file-specification 


(FIXED=(1-16383) 
[FORMAT] = |(VARIABLE=[1-16383] 
(CONTROLLED=[1-16383) 


[SIZE=(1-2551] 


[ BLOCK__SIZE=(18-327671)] 


/SEQUENTIAL 
/RELATIVE 
/JINDEXED__SEQUENTIAL 


[ /ALLOCATION=(1-4294967295) ] 
[ /CONTIGUOUS] 
[/OVERLAY | 


[ BUCKET_SIZE=(1-32]] 
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Notes 


See Appendix D for file-specifications. 
DAT is default file-type. 


RECORD_SIZE is not normally 
specified. 


FILE__SIZE is not normally specified. 


Notes 


See Appendix D for file specifications. The 
default output file type is the same as in- 
put file type. 


FIXED record format is default if sort pro- 


cess is index or address. 


Used for VFC records only. Default value is 
2 if CONTROLLED is specified and SIZE 


is not. 
For magnetic tape files only. 


Default is the input file organization if sort 
process is record or tag, otherwise 
/SEQUENTIAL is”~ default. If 
JAINDEXED__SEQUENTIAL is specified, 
/OVERLAY must be specified. 


Required if /CONTIGUOUS is specified. 
The default value is determined by the 
number of records sorted. 


/NOCONTIGUOUS is default. 
/CONTIGUOUS is invalid if 
/ALLOCATION is not specified. 


/NOOVERLAY is default. /OVERLAY is 
required if INDEXED SEQUENTIAL out- 
put file organization is specified. 


Default value is the same as_ the 
input file value if the input and output file 
organizations are the same, otherwise 
default is 1. 


2.2 Interactive Sessions 


To invoke SORT in interactive mode simply enter the SORT command. Any 
errors in the command are immediately reported at your terminal (see Chap- 
ter 4, Error Conditions). At the end of a successful run, SORT prints the 
statistics message (see Section 2.2.3). 


SORT accepts two kinds of command formats: a keyboard-oriented command 
string containing all the command qualifiers (excluding /SPECIFICATION), 
or a keyboard-oriented command string containing the /SPECIFICATION 
qualifier pointing to a specification file containing the command qualifiers. 


For example: 


¢ SORT/KEY=(POSITION=1,SIZE=10) input-file-specification 
OoOuteut-file-specification (él 


or: 


$ SORT/SPECIFICATION=file-srecification 
inmput-file-specification outeput-file-specification (QE 


The use of the specification file is the more involved method and therefore 
explained in Section 2.5. 


In order to specify a sorting sequence, you must select key fields within the 
data itself. Remember, SORT reorders the entire file. The information pro- 
vided in Section 2.6 can help you to set up the key fields (keys). 


You can extract key information from a file and store it in a reordered format 
for future use in accessing data in your original file in the order of your 
reordered file. In addition, the contents of your sorted file can be entire 
records, key fields with record pointers, or record indices relative to the posi- 
tion of each record within the file. Your intentions for the sorted output file 
usage, together with input and output file organizations, determine what sort 
process to use. The information provided in Section 2.2.2 can help you to 
choose the correct sorting process. 


Because SORT is designed to process all RMS file organizations, you also 
must consider how to direct the sorting process you have chosen, so that your 
output file organization will be usable on your peripheral device. The informa- 
tion provided in Section 2.2.2 and Table 2-2 compares file organizations and 
sorting processes. 


If your sorting task requires more than two work files, Section 2.7 can help you 
to set up additional work files. Most sorts will normally use the default num- 
ber of work files. 


Finally, you must specify input and output file specifications. Appendix D 
reviews the standard VAX/VMS file-specification information, and file speci- 
fication qualifiers are summarized in Table 2-1, and described in detail in 
Section 2.4. 
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2.2.1 A Sample Sort 


Users can invoke the SORT command by simply providing the required key 
position and size for a single key and the file name of a single input file 
located on the user’s default disk. 


The format of the command is: 


$ SORT/KEY=(POSITION=£1-i163831] ,SIZE=C1-2551) 
imPut-file-specification output-file-specification (RET 


This means: 


e A record sorting process is performed on the specified input file 
e The input file key data type must be character 
e The input file must reside on the user’s default disk 


e All the records in the input file are reordered in the output file in ascending 
alphabetic order 


¢ Input file type DAT is assigned, and output file type DAT is assigned 
e SORT assigns two work files for temporary storage 

¢ Output file organization is the same as the input file organization 

¢ Output file record format is the same as input records format 

e Output file bucket size is the same as input file bucket size 


¢ SORT statistics are printed at the terminal that executed the sort 
An abbreviated representation of the preceding command example is: 


$¢ SORT/K=(PO#1,S1T=80) INPUT OQUTPUT @Er 


Description: 


If you specify the key position and size, and character data type by default; 
this sort reads the single input file specified (on the user’s default disk), sets 
up two work files on the user’s default disk, and performs a record sort. 


This process creates an output file named OUTPUT.DAT having the same 
file organization as the input file. All the records in INPUT.DAT are reor- 
dered in ascending alphabetic order in the output file. The alphabetic order is 
determined by the contents of the 80-character key field (SI=80) starting in 
position one (PO=1) of each record. 


NOTE: 


A quick test can be run at your terminal by using 
SYS$OUTPUT as the output-file-specification. This technique 
displays the sorted output file before the sort statistics are 
printed. 
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Finally, upon completion of the run the sort statistics are printed at the 
terminal that executed the sort. 


2.2.2 Selecting the Sort Type 


SORT offers a choice of four processes: record, tag, address, and index. You 
specify the sort process by using the proper qualifier in the command or in the 
specification file code. Each process has its particular input requirements, 
processing methods, device requirements, and resultant output files. 


SORT provides four sorting techniques: 


¢ RECORD (/PROCESS=RECORD, or SORTER if specification file) 
Record sort produces a reordered data file sorted by specified key fields 
(that is, entire records are reordered). This sort can be used on any accept- 
able input device, and can process any valid VAX-11 RMS format. Record, 
a relatively slow sort, is the default process. 


TAG (/PROCESS=TAG, or SORTT if specification file) 

Tag sort produces the same kind of reordered data file as record sort by 
sorting only the record keys. This method conserves temporary storage, but 
can only accept input files residing on disk. Tag sort is faster than record 
sort, if the key size is much smaller than the record size and the file size is 
small so that the reaccessing process is short. 


ADDRESS (/PROCESS=ADDRESS, or SORTA if specification file) 
Address sort produces an address file without reordering the input file. That 
is, a reordered address file (on disk only) of record’s file addresses (RF As). 


The address file, sorted by record keys, can later be used as an index* to 
read the original file in the desired sequence. Any number of address files 
may be created for the same data base. A customer master file, for instance, 
may be referenced by either customer-number index or sales-territory index 
for different reports. This is the fastest of the four sorting processes. 


INDEX (/PROCESS=INDEX, or SORT] if specification file) 

Index sort produces an address file containing the key field of each data 
record and a pointer (RFA) to its location in the input file. The address file 
can be used by programs to randomly access data from the original file in 
the desired sequence. Like Address sort, this is a high speed process. 


Figure 2-1 summarizes these options to help you determine which process is 
best for your sorting application. Chapter 5 provides additional information 
regarding sorting processes where performance considerations are important. 


* Not indexed by VAX-11 RMS. 
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(Disk,Magtape,Cards, Terminal) 


Figure 2-1: SORT’s Four Sorting Processes 
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For !ater use to access the original 
File when this particular sequence 


ADDRE 








Input Data File 













(Disk Only) 







Keys + RFA’s 
only. 













is desired. 
Temporar 
(Work Files) 2-10 Files. 
Keys + RFA’s Output Address File 
Only. of Record’s File Address (RFA) 
Records (fixed 6-byte records) 


pl 







INDEX Sort\ a gi & 
(A fast process if Key ana 1 ‘? 
Size is less than Record.) \QQha44 45 





RFA in binary + Key 
(Disk or ANS! Magtape) 


For later use to randomly access the 
original File in the desired sequence. 
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File 1/O Considerations 


Input and output file organizations are another important factor in determin- 
ing which sort type to use. Figure 2-2 shows how the I/O flows through SORT, 
and Table 2-2 list all possible I/O combinations and shows the default output 
file organizations. 


inputs to V.AX-11 SORT can be files of sequential, relative, or indexed organiza- 
tion containing records of fixed, variable, or VFC format from disk, magnetic 
tape, card reader, or terminals. 


Input parameters to the sort program are either provided by RMS after proc- 
essing the input file header records, or specified in the command in the form 
of input-file-specification qualifiers (that is, /FORMAT ...). 


Outputs fram VAX-11 SORT are files of records reordered by key fields and are 
created in sequential, relative, or indexed organization. These files may con- 
tain record types of fixed, variable, or VFC format. Output files can be written 
to disk, magnetic tape, printer, or terminals. 


Sorted output address files of 6-byte RFAs in binary coded records are output 
to disk only for sequential access by programs. These output address files are 
intended for software use as indices into input files, and cannot be output to 
printers or terminals without further processing. 


Output parameters to the sort program are specified in the command in the 
form of output-file-specification qualifiers (that is, /FORMAT ...). 
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Figure 2-2: File Organization I/O Flow 


INPUT | OUTPUT 


SEQUENTIAL 
_DATA FILE 
SEQUENTIAL SEQUENTIAL 


DATA FILE 


oN 


ADDRESS FILE 


RELATIVE 
DATA FILE 


RELATIVE 
DATA FILE 


SEQUENTIAL 
ADDRESS FILE 


Sn Re eipers yeaa ema EET 





INDEXED-SEQUENTIAL : INDEXED 
DATA FILE ——- 0. SG opaTA FILE 


SEQUENTIAL 
(ADDRESS FILE 


NOTES: 


1. RECORD & TAG produce reordered data files of the same organization as input 
by default. 


2. INDEX produces reordered address files of RFA’s plus keys in sequential file 
organization. 


3. ADDRESS produces reordered address files of RFA’s only in sequential file 
organization. 
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Table 2-2: File I/O Considerations 














Output File 
Organization 
Specified 





Sort 


Input File | Process Results 









Reordered sequential data file. 
Reordered file of data records. 
Populates (overlays) an already existing Indexed- 
Sequential output file with reordered data records. 


Sequential 
Relative 
Indexed-Seq 






Record 



















Sequential 
Relative 
Indexed-Seq 


Sequential | Tag Same as for record. 


Data File 


Sequential 
Relative 
Indexed-Seq 


Address Sequential address file of RFAs. 







Sequential 
Relative 
Indexed-Seq 


Index Sequential address file of RFAs with keys. 





Sequential 
Record | Relative 
Indexed-Seq 





Sequential 
Relative Tag Relative 
Data File Indexed-Seq Same as above for each process. 








Sequential 
Relative 
Indexed-Seq 





Address 








Sequential 
Relative 
Indexed-Seq 














Sequential 
Relative 
Indexed-Seq 





Record 







Indexed- 
Sequential 
Data File 


Sequential 
Tag Relative 
Indexed-Seq {Same as above for each process. 


Sequential 
Address | Relative 
Indexed-Seq 


Sequential 
Index Relative 
Indexed-Seq 


SR 


Note: The default output file organization is shown in italic type. 
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. 2.2.3 SORT Statistics 
Statistics are automatically printed at the completion of each sort session. 
These consist of: elapsed execution time, the number of records read, sorted, 
and output; the longest record length; the multiblock count used and the 
multibuffer count used for input and output; the merge order; the number of 
merge passes; the working set size used; the number of initial runs; and the 
_ virtual memory used for the sort tree. 


In addition, SORT statistics include statistics kept by VAX/VMS for the 
number of buffered and direct I/O operations, CPU time, and the number of 
page faults. Figure 2-3 illustrates a typical SORT statistics printout of a 
single sequential input file (filename R100SQ.DAT) that is 10,000 records in 
length, and each record is 80 characters long. The sorting is done on an 80 
character key starting at position 1 of each record. The output filename is 
TEST.TMP and is output in the same format as the input file by default. 


The command string that caused the sample printout in Figure 2-3 was: 
$ SORT/KEY=(POS=1,SIZE=80) (er 


$ File: riaosa 
$OutPputseTEST.TMP RED 


The statistics can be used to help tune the parameters you specify for a 
specific sort, such as the best working set quota size to use (see Chapter 5, 
Section 5.2.2.5). 

Figure 2-3: Sample Sort Statistics Printout 


SORT STATISTICS: 


RECORDS READ: 10000 LONGEST RECORD LENGTH: 380 
RECORDS SORTED: 10000 INPUT MULTI BLOCK COUNT: 11 
RECORDS QUTPUT: 10000 OUTPUT MULTI BLOCK COUNT: 206 


MAXIMUM WORKING SET USED: 128@ INPUT MULTI BUFFER COUNT: 2 
VIRTUAL MEMORY ADDED: 236032 @ OUTPUT MULTI BUFFER COUNT: 2 


DIRECT IO COUNT: 227 NUMBER OF INITIAL RUNS: 38 
BUFFERED I0 COUNT: 23 ORDER OF THE MERGE: 7 
PAGE FAULTS: 15596 NUMBER OF MERGE PASSES: 2 
ELAPSED TIME: 00:02:26,976 CPU TIME: 5055 @ 

$ 


Notes: @ Maximum working set used is in blocks. 
@ Virtual memory added is in bytes. 
© Elapsed time is the total sort run time from start to end in hrs: min: sec. 
1/100secs. : 
© CPU time is the data processing time less I/O time in 1/100secs. (that is, 5055 
is 50 seconds and 55/100th’s seconds.) 


2.2.4 Samples 


Figure 2-4 shows a step-by-step session for an interactive sort on a single key. 
Figure 2-5 shows how an interactive sort would appear when sorting on two 
keys. 
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Figure 2-4: Interactive Session Sample #1 


Step 1: Observe the input file you want to sort to determine where the key fields are 
located and their size. 


To sort this input file named BOATS.LST in alphabetic order by manufacturer you must 
specify a single key field starting at character position 2 and having a key field size of 10 


characters. 


MANUFACTURER MODEL 


NORTHERN 


CHALLENGER 


OLYMPIC 
EASTWARD 
AMERICAN 
LINDSEY 


WINDPOWER 
CAPE DORY 


VENTURE 
SALT 
AMERICAN 
HUNTER 
TANZER 
ALBIN 
GRAMPIAN 


CHRIS-CRAF 


ISLANDER 
COLUMBIA 


37 
4i 


ADVENTURE 


HO 
26~-MS 
39) 
IMPULSE 
TYPHOON 
2ee2 

19) 

26 

a7 

28 
BALLAD 
2~34 


CARIBBEAN 


36 
44 


RIG 


KETCH 
KETCH 
KETCH 
M/S 

M/S 

M/S 

SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 


/KEY=(POSITION=2,SIZE:=10) 


LENGTH 


37 
441 
Ae 
24 


WEIGHT 


145900 
26 +700 
247230 
74~OQ0Q 
3900 
14,500 
650 
1,900 
2,000 
29600 
4,000 
6,500 
6800 
79276 
11800 
18,000 
13,4350 
20,700 


BEAM 


PRICE 


$50,000 
$51,228 
$80,500 
$15,900 
$18,895 
$35 ,900 
$3,500 
$4,295 
$3,564 
$6,590 
$9,895 
$14,999 
$17,300 
$27,500 
$29,675 
$37,850 
$315,730 
$48,490 


Step 2: Enter the following SORT command to sort the input file named BOATS. LST and 
create an output file named BOATS.ALB: 


$ SORT/KEY=(POS=2;STZE=10) 


BOATS.LST BOATS.ALB ed 
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Step 3: Observe this printout when SORT has completed. 


SORT STATISTICS: 


RECORDS READ: i8 LONGEST RECORD LENGTH: 57 
RECORDS SORTED: 18 INPUT MULTI BLOCK COUNT: 20 
RECORDS OUTPUT: 18 OUTPUT MULTI BLOCK COUNT: 32 
MAXIMUM WORKING SET USED: 200 INPUT MULTI BUFFER COUNT: 2 
VIRTUAL MEMORY ADDED: 404992 OUTPUT MULTI BUFFER COUNT: 2 
DIRECT 10 COUNT: 2 NUMBER OF INITIAL RUNS: 0 
BUFFERED I0 COUNT: 17 ORDER OF THE MERGE: s) 
PAGE FAULTS: 146 NUMBER OF MERGE PASSES: 9 
ELAPSED TIME: 00:00:04.97 CPU TIME: 34 


$ 


Step 4: Examine your newly sorted output file named BOATS.ALB. Notice that the re- 
cords are now in alphabetical order. 


2-14 


MANUFACTURER MODEL RIG LENGTH WEIGHT BEAM PRICE 
ALBIN BALLAD SLOOP 30 7+276 10 $27,500 
AMERICAN 26 SLOOP 26 4,000 08 €9,895 
AMERICAN 26-MS M/S 26 57900 08 $186,895 
CAPE DORY TYPHOON SLOOP 19 1,900 OG $45,295 
CHALLENGER 41 KETCH 41 26;700 13 $51+228 
CHRIS-CRAF CARIBBEAN SLOOP 35 18,000 11 $37,850 
COLUMBIA 4i SLOOP 4i 20;700 11 $48,490 
EASTWARD HO M/S 2g 7,000 O09 £#$15,900 
GRAMPIAN 2-34 SLOOP 34 11,800 10 295675 
HUNTER z SLOOP 27 6-500 09 $14,999 
ISLANDER 36 SLOOP 36 13,450 11 =$31;+730 
LINDSEY 39) M/S 39 14,500 12 €35,;900 
NORTHERN 37 KETCH 37 14,000 11 $50,000 
OLYMPIC ADVENTURE KETCH 42 249250 13 $80,500 
SALT i9 SLOOP 25 21600 O07 $6 +590 
TANZER 28 SLOOP 28 G,800 10 $17+500 
VENTURE Lee SLOOP 22 299000 07 $3,564 
WINDPOWER IMPULSE SLOOP 16 650 O07 $39,500 
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Figure 2-5: Interactive Session Sample #2 


Step 1: Observe the input file you want to sort to determine where the key flelds are 
located and their size. ) 


To sort this input file named BOATS.LST in ASCII alphanumeric order first by beam, and 
then by price, you must specify two keys. The first key (or primary key) field starts at 


character position 47 and has a size of 2. The second key starts at 


and has a size of 7. 


MANUFACTURER MODEL 


NORTHERN 
CHALLENGER 
OLYMPIC 
EASTWARD 
AMERICAN 
LINDSEY 
WINDPOWER 
CAPE DORY 
VENTURE 
SALT 
AMERICAN 
HUNTER 
TANZER 
ALBIN 
GRAMPIAN 
CHRIS-CRAF 
ISLANDER 
COLUMBIA 


41 
ADVENTURE 


CARIBBEAN 
36 
41 


RIG 


KETCH 


KETCH 
KETCH 
M/S 

M/S 

M/S 

SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 
SLOOP 


LENGTH 


37 
41 
42 
24 
26 
39 
16 
19 


‘20 
26 
a7 
28 
gO" 
34 
go 
36 
41 


/KEY=(POS=47, SIZE=2) 
/KEY=(POS--51,SIZE=7) 


WE I GHT 


14,000 
26+700 
£45250 
7+QO00 
2 +000 
14,800 
G50 
1*°900 
279000 
2 +600 
4,000 
69500 
6 +800 
79276 
11,800 
18 +000 
13,450 
209700 


BEAM 


PRICE 


$50,000 
$51+228 
$80 +500 
$15,900 
$18,895 
$395,900 
$3 +500 
$45,295 
$3,564 
$6,590 
$9,895 
$14,999 
$17,500 
$27 +500 
$29,675 
$37,850 
$315730 
$48,490 


character position 51 


Step 2: Enter the following SORT command to sort the input file named BOATS.LST and 


create an output file named BOATS.BEM: 


$ 


SORT/KEY= (POS247 ,SIZE=2)/KEVY=(POS=231 +S12E=7) 
BOATS.LST BOATS.BEM fed 
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Step 3: Observe this printout when SORT has completed. 


SORT STATISTICS: 


LONGEST RECORD LENGTH: 57 
INPUT MULTI BLOCK COUNT: 20 
OUTPUT MULTI BLOCK COUNT: 17 
INPUT MULTI BUFFER COUNT: 2 
OUTPUT MULTI BUFFER COUNT: 2 
NUMBER OF INITIAL RUNS: 9 
ORDER OF THE MERGE: 0 
NUMBER OF MERGE PASSES: QO 
CPU TIME: 45 


RECORDS READ: 18 

RECORDS SORTED: 18 

RECORDS OUTPUT: 18 

MAXIMUM WORKING SET USED: 200 
VIRTUAL MEMORY ADDED: 202240 
DIRECT 10 COUNT: 2 

BUFFERED I0 COUNT: 17 

PAGE FAULTS: 142 

ELAPSED TIME: 00:00:01.85 

$ 


Step 4: Examine your newly sorted output file named BOATS.BEM. Notice that the 
records are now in order first by beam width, and second by price. 
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MANUFACTURER MODEL RIG LENGTH WEIGHT BEAM PRICE 
CAPE DORY TYPHOON SLOOP 19 1,900 O06 $4295 
WINDPOWER IMPULSE SLOOP 16 650 07 $3 9500 
VENTURE 222 SLOOP 22 21000 07 $3564 
SALT 19 SLOOP 29 29600 07 $6 5590 
AMERICAN 26 SLOOP 26 4,000 08 $9+895 
AMERICAN 26-MS M/S 26 270900 O8 $18,895 
HUNTER 27 SLOOP 2/7 6Gs500 O09 $14,999 
EASTWARD HO M/S 24 7:000 O09 $15,900 
TANZER 28 SLOOP 28 6s800 10 $175500 
ALBIN BALLAD SLOOP 30 79276 10 $27,+500 
GRAMPIAN 2-34 SLOOP 34 11,800 10 295675 
ISLANDER 36 SLOOP 36 139*450 11 £$31+7390 
CHRIS-CRAF CARIBBEAN SLOOP 3 18,000 11 $37,859 
COLUMBIA 41 SLOOP 41 20*700 11 $48,490 
NORTHERN 37 KETCH 37 14,000 11 $30,000 
LINDSEY 39 M/S 39) 14°500 12 $35,900 
CHALLENGER 41 KETCH 41 26*700 13 $517228 
OLYMPIC ADVENTURE KETCH 42 245250 13 #805500 


2.3 Batch Sessions 


To run the same sort as shown in Figure 2-4 using batch mode, perform the 
following steps: 


Step 1: Create a command file named BOATS1.COM as follows: 


$ PRINT BOATS.LST 
$$ SORT/KEY=(POS=2,SIZE=10) BOATS.LST BOATS.ALB 
$ PRINT BOATS.ALB 


Step 2: Enter this command: 


¢ SUBMIT BOATS1.COM @eD 


Observe this response: 
Job n entered on aueue SYS$BATCH 


Step 3: Observe that the input file, output file, sort statistics, and batch 
statistics are all printed on the system printer. 


2.4 The SORT Command Description 


NOTE: 
Review the SYMBOLOGY in the front of this manual before 
continuing. 
Format: 


¢ SORTCaualifiers] ineput-file-specificationfaualifiers] 
OutPut-file-specificationlaualifiers] Qe 


2.4.1 Command Name Quallfiers 


Abbreviated asian 





es fii. eee Pe a ea 
OutPUut-file-specificationfCoaualifiers] (ed 


RECORD 
TAG 
/PROCESS= ADDRESS 
INDEX 
Indicates the type of sort to be performed. /PROCESS=RECORD is the 


default. 
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/KEY= 


This qualifier must be specified unless defined in a specification file. It de- 
fines a sorting key, and may appear several times in a single command string 
in order to specify several sort keys (up to 10). 


NOTE: 


The /KEY subqualifiers group must be enclosed in parentheses. 


([NUMBER=n] 


n specifies the precedence of the sort key being defined, where 1 is the 
primary sort key, 2 is the secondary sort key, and so on. If this option is 
not specified on the first /KEY qualifier, NUMBER=1 is assumed. If 
this option is not specified on subsequent /KEY qualifiers, the default 
NUMBER value is the NUMBER value of the previous key plus 1. 
Legal values are 1 - 10. 


,POSITION=n 


n specifies the position of the key within each record, where the first 
character of the record is 1. This subqualifier input must be specified. 


»oIlZK=n 


n specifies the length of the sort key in either characters, bytes, or 
digits, depending on the key field data type. This subqualifier input 
must be specified. If the sort key data type is CHARACTER, key size 
must be less than or equal to 255 characters. If the data type is binary, 
key size must be 1, 2, or 4 bytes. If the data type is any of the decimal 
types, key size must be less than or equal to 31 digits. The total of all 
key field sizes must be less than or equal to 255 bytes. See Section 2.6 
for additional key size information. 


,;CHARACTER 
»,BINARY 

ZONED 

»DECIMAL 
,PACKED__DECIMAL 


This subqualifier indicates the type of data appearing in the sort key 
field. See Section 2.6 for data type descriptions. CHARACTER is the 
default. 
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, TRAILING_SIGN 


This subqualifier indicates whether the sign of a decimal data type key 
appears at the beginning or end of the key. If the key data type is 
DECIMAL and this option is not specifed, TRAILING__SIGN is the 
default. See Section 2.6 for key descriptions. 


Cree 


,OVERPUNCHED__SIGN 
»EPARATE__SIGN 


This subqualifier indicates whether the sign of a decimal data type key 
is superimposed on the decimal value or is separate from the decimal 
value. If the key data type is DECIMAL and this option is not speci- 
fied, OVERPUNCHED__SIGN is the default. See Section 2.6 for key 
descriptions. | 


ASCENDING 
,DESCENDING 


Indicates whether the key is to be sorted into ascending or descending 
order. ASCENDING is the default value. 


[ /WORK__FILES=n] 


n specifies the number of temporary work files to be used during the sort. 
Values of 0, or from 2 to 10 may be used. Default value is 2. 0 specifies no work 
files because data will fit in real memory. See Section 2.7 for additional 
information. | 


/SPECIFICATION[=file-specification]] 


Specifies the name of a file which contains SORT specification statements. If 
this qualifier is not specified, a standard sort is performed. See Section 2.5 
and Appendix D for additional information. SYS$INPUT is the default value. 


[ /RSX11] 


Indicates that SORT-11 (/RSX11) is to be invoked. The SORT-11 command 
format and switches are not described in this manual. Refer to the PDP-11 
SORT Reference Manual when using the /RSX11 qualifier. VAX-11 SORT is 
the default value. 
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NOTE: 


Only the minimal unique abbreviated form of qualifier and 
parameter inputs are required, but all four character abbrevia- 
tions are accepted (for example, enter SPE= for 
SPECIFICATION=SYS$INPUT). 


An abbreviated example is: 


$ SORT/KEY=(NUM=1,POS=12-SIZE=2,DECI)/SPE= 
inPut-file-~specificationCaualifiers] 
outPuUt-file-srpecificationLaualifiers] Qe 


The actual example including defaults is: 


$SORT/PROCESS=RECORD/KEY=- 
(NUMBER=1,+POSITION=12,SIZE=2 ,~ECIMAL »>TRAILING.SIGN:- 
QVERPUNCHED_SIGN ASCENDING) /WORK_FILES=2- 
/SPECTIFICATION=SYS$INPUT - 
inPput-file-specificationCaualifiers] 
output-file-specificationCaualifiers] Qe 


2.4.2 Input-File-Specification Qualifiers 


Defines input file attributes. 


Format: 


$ EMBER ES ORERES SNP UL cere specification- 





aria elas STREET nee RET) 


NOTE: 


If the input file name does not contain a file type, the default 
file type becomes DAT. 


If only one FORMAT subqualifier is specified, the parentheses 
() can be omitted. 


[ /FORMAT=(RECORD__SIZE=n ] 


This input should be used only to override the record size input normally 
retrieved from RMS. Omitting RECORD__SIZE indicates that the file record 
format is to be obtained from the file header or label. n specifies the longest 
record length (LRL) in bytes. The LRL input is optional, but should be 
specified if the input file is not on disk or is inaccurate. The longest record 
length allowed is 16,383 bytes (not including control bytes). For additional 
information on determining the LRL, refer to the $FAB MRS parameter in 
the VAX-11 Record Management Services Reference Manual. Note, stream 


format is not supported because VAX-11 RMS does not support it. 
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[FILE__SIZE=n)] 


This input should only be used to supply the file size normally pro- 
vided by RMS when the input file is not on disk. This input is used to 
determine the size of the work files based on input file size. n specifies 
the input file size in blocks. Default is 1000 if file size cannot be 
obtained from RMS and is not specified by the user. Maximum file 
size is 4,294,967,295 blocks. 


2.4.3 Output-File-Specification Qualifiers 


Defines output file attributes. 


Format: 


$ SORTCaualifiers] input-file-~specificationlanualifiers] 





NOTE: 


If the output file name does not contain a file type, the output 
file type becomes the same as the input file type. 


If only one FORMAT option is specified, parentheses () may be 
omitted. 


[ /FORMAT=] 


(FIXED=n 
(VARIABLE=n 
(CONTROLLED=n 


Indicates the output file record format. n specifies the longest record 
length (LRL) of the output records in bytes, and is optional. The 
longest record length allowed is 16,383 bytes (less any control bytes). 
Default is input file record format if record or tag sort, and FIXED if 
index or address sort. For additional information on determining the 
LRL, refer to the $FAB MRS parameter in the VAX-11 Record Man- 
agement Services Reference Manual. 


|. SIZE=n] 


This input applies to CONTROLLED records only. That is, variable 
with fixed-length controlled (VFC) records. n specifies the size in bytes 
of the fixed portion of controlled records. Maximum fixed control area 
size is 255 bytes. If CONTROLLED is specified, and SIZE is not, 
default is two bytes. 
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[BLOCK_SIZE=n )] 


This input applies to magnetic tape files only. n specifies the block 
length in bytes of the output file. Default value is the block size of the 
input tape file, or that which was established at tape mounting time. 
Block length must be in the range of 18 to 65,535 bytes. 


NOTE: 


To ensure for correct data interchange with other DIGITAL 
systems, you should specify a block size less than or equal to 
512 bytes. To ensure compatibilty with most non-DIGITAL 
systems, the block size should be less than or equal to 2048 
bytes. 


/SEQUENTIAL 
/RELATIVE 
AINDEXED__SEQUENTIAL 


Indicates the organization of the output file. If [NDEXED_SEQUENTIAL 
is specified, the output file must already exist and must be empty; therefore, 
/OVERLAY must be specified. Default is the input file organization if a 
record or tag sort (/(PROCESS= RECORD or /PROCESS=TAG) is performed. 
Otherwise, /SEQUENTIAL is default. 


[ /ALLOCATION=n] 


n specifies the number of 512-byte blocks of disk space to be allocated for the 
output file. The default value is whatever the output requires based on the 
number of records sorted. Blocks allocated must be in the range of 1 to 
4,294,967, 295. 


[ CONTIGUOUS ] 


Indicates contiguous allocation of blocks for output file. Default is /NOCON- 
TIGUOUS. This qualifier is invalid if /ALLOCATION is not specified, or if 
/ALLOCATION value is insufficient for total output and the file must be 
extended. 


[ /OVERLAY ] 


/OVERLAY indicates that an existing file which has the same name as the 
output file should be overwritten with the SORT output. /OVERLAY requires 
that the existing file must be empty. Default is /NOOVERLAY. 


[ /BUCKET_SIZE=n] 


n specifies the RMS bucket size (that is, the number of 512-byte blocks per 
bucket) for the output file. If the output file has the same organization as the 
input file, the default value is the same as input file bucket size. The maxi- 
mum number of blocks per bucket is 32. If the output file organization is 
different from the input file organization, the default value is 1. 
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2.5 Specification File 


Use of the /SPECIFICATION qualifier in the SORT command allows SORT 
to be controlled by SORT specification statements. These statements are 
contained in the header record and field records of a specification file, and 
provide a means for expanding the range of sorting features. 


Having sort processes controlled by specification files enables dynamic pro- 
gram control of specification file statements, and therefore dynamic control of 
subsequent sort processes using the same specification file modified. Also, 
specification file libraries can be maintained for often-used sorts. 


The command string for a typical standard sort using a specification file 
would look like this: 


$ SORT/SPECIFICATION(T =specification filel ; 
imput-file-specification outeput-file-specification @ED 


There are several methods of entering the /SPECIFICATION qualifier. If you 
allow the predetermined specification file statements to control the sort, 
SORT will run automatically with no further operator prompts. 


Example: 


$ SORT/SPECIFICATION(C=file-specification 
of the predetermined specification file] 
imeput-file-specification 
outPut-file-specification QED 


However, if you use the default specification file (that is, =SYS$INPUT, and 
providing your terminal is set to be the input device), SORT will prompt you 
for the specification file values. 


Example: 


$ SORT/SPECIFICATION 
imPut-file-~specification 
OuUtPHt-file-specification (eT 
PLEASE ENTER SPECIFICATION FILE RECORDS. 
-jenter the specification file header record values (ed 
~enter the specification file field record values for 
the ist Key field (ED 


cd > > > 


~enter the specification file field record values for 
the last Key field CR 
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If you allow SORT to prompt you for the input and output files as well as the 
specification file values, then the SORT command will be input in the follow- 
ing sequence: 


$ SORT/SPECIFICATION RE 

~file: input-file-specification (Eé 

-QUTPUT: outeput-file-specification (Eé 

PLEASE ENTER SPECIFICATION FILE RECORDS. 

“enter the specification file header record values QED 

—~enter the specification file field record values for 
the ist Key field QE 


> > > > 


-~enter the specification file field record values for 
the last Key field CrAL/2 


2.5.1 Specification File Records 


The specification file records can have either of two formats; fixed position 
field format (SORT-11), and logical position field format (VAX-11 SORT). 


NOTE: 


Since omit/include and alternate collating sequences are not 
supported, ALTSEQ records and record type records are in- 
valid and cause errors. Only header and field specification re- 
cords are processed. 


Fixed Position Field Format (SORT-11) 


In order to allow ease of conversion from SORT-11 V2 use to VAX-11 SORT, 
the existing fixed-position-fields format of SORT-11 is accepted. 


Free Field Format (VAX-11 SORT) 


To allow some flexibility for new users, fields may be separated by commas, 
and records may be variable length up to 132 characters. Blanks are ignored 
unless they are embedded within a field, such as 1 00, in which case an error is 
generated. Continuation lines are supported as in DCL. The individual fields, 
their length, meaning and order are identical to SORT-11. 


Comments in this format are placed at the end of the line by placing an 
exclamation point (!) immediately before the comment. The format for a 
VAX-11 SORT header record would look like: 


Page numberrline niumbersHersort tyPertotal Ker field sizes 
sorting order;collating seanencesouteput Keysrecord Length 
lcomment 
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DEC 7-(362}-1133A-R 1172 


A specific example would be: 


LelsoHs s1 9D sAr eK 132 lheader for record sort ascending - 
orders Key field size 10, 


2.5.2 Specification File Record Formats 


Two record types and two record formats exist for specification files. The two 
record types are header records and field specification records. Each record 
type may contain either fixed position fields to support SORT-11 compatible 
files, or free fields for VAX-11 SORT. 


2.5.2.1 For SORT-11 Type Files (fixed position fleids) — A DIGITAL SORT 
specification form is available for use when setting up fixed position fields (see 
Figure 2-6). 


Figure 2-6: SORT Specification Form 
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The format of each type of SORT-11 specification record is fixed. The SORT 
specification form is based on card columns, as shown in Figure 2-6. The 
following entries are common to both types of specification file lines. 


Column Entry Notes 
1-2 Page number Required only when different types of records are to be 
described. A separate page, numbered in ascending sequence, 
should be used for each record type and its corresponding Field 
Specifications. Only the first page has a header specification. 
3-5 Line number Specifies line sequence. If column 5 is blank, 0 is assumed. 


Thus a digit entry in this column can be used to identify later 
line insertions. 


6 Specification Type H for Header, or F for Field 


In the following material, unless otherwise stated, these criteria apply: 


e Numeric data is decimal. 


e Either leading zeroes or leading blanks are acceptable in right-justified 
entries. | 


e All field position definition records begin at column 1. 
Table 2-3 summarizes all fixed position SORT specification entries. 


Header Record: 


The first record in a specification file must be the header. The header tells the 
SORT program what kind of sorting process to use, key field size, sorting 
order, and output record size. 


Format: 
Field 
Position Function Legal Values 
1-2 Page number Any number or blanks 
3-5 Line number Any number or blanks 
6 Header record ID H 

7-12 Sorting process SORT R,1,A,T or blanks 

13-17 Total key field size Any number or blanks 
18 Sorting order A, D, or blank 

19-25 (not used) Blanks (anything-ignored) 
26 (not used) Blank (anything-ignored) 
27 (not used) Blank (anything-ignored) 
28 (not used) Anything-ignored 

29-32 Output record length Any number or blanks 

33-132 (not used by SORT, may be Anything-ignored 
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used for comments) 
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Notes and Comments on Header Specification Entries: 


Columns Explanations and Legal Entries 


7-12 Type of SORT (must be left-justified) 
Legal values: SORTR or blanks - Record sort 
SORTT - Tag sort 
SORTA - Address sort 
SORTI — Index sort 


13-17 Total of all key field sizes 
Legal values: 1-255 
Must be equal to the total size in bytes of the largest record 
key on the file and right-justified. 


18 Normal sort order sequence 
Legal values: A or blank - ascending 
D - descending 


This field may be qualified by N or O entered in column 7 of the field 
specification. 


29-32 Output Record Length (for SORTR and SORTT only) 
Legal values: A decimal number (right-justified) equal to the number of 
bytes in the largest output record. : 


To determine this number, add the sizes of the key fields in the field specifi- 
cations for the largest record in the file. If neither SORTT nor SORTR are to 
be run at this time, an entry in this field is not needed. 


Field Specification Records: 


The field specification records follow the header record and specify key fields 
(up to ten). 


NOTE: 


Data fields are not supported since each entire record in a file is 
written to the output file for SORTR and SORTT. For SORTA 
or SORTI, output files contain only pointers and possibly some 
restricted-format key data. 


Format: 
Field 
Position Function Legal Values 
1-5 Page/Line number See Header Specification 
6 Field record ID F 
7 Key field order N or O 
8 Key field type B,C,D,I,J,K,P,Z 
9-12 First byte of field Any number or blanks 
13-16 Last byte of field Any number or blanks 
17-19 (not used) Anything-ignored 
20-80 (not used - available Anything-ignored 


for comments) 
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Notes and Comments on Field Specification Entries: 


Columns Explanations and Legal Entries 


7 Key Field Order - specifies keys and their sort sequence (this entry can satisfy 
the column 18 entry for the Header Specification). 


Legal values: N - normal sort sequence 
OQ - opposite sort sequence 


8 Key field data type codes: 
B - Binary (two’s complement binary) 


C - Character (8-bit ASCII coded alphanumeric characters). This is the de- 
fault data type. 


D - Decimal data with sign trailing and overpunched. 


I- Same as D, but with the sign leading and separate, so that the first byte of 
the field is a + or -. 


J - Same as I, but with the sign trailing and separate. 
K - Same as D, but with the sign leading and overpunched 
P - Packed-decimal format. 


“% - Zoned ASCII format. 
9-12 Field location (location of the first byte of a multi-byte key field). 


Legal values: A decimal number (right-justified) specifying the first byte of 
a key field. 


Blanks can be used to specify a one-byte key field. 
13-16 Field location (location of the last, or only, byte of a key field). 
Legal values: A decimal number (right-justified) specifying the last byte, 
or the only byte, in a key field. 


Table 2-3: Fixed Position SORT Specification Summary 


AMIR Mae 1M WS Ls tA 


Header Specifications 


Column Entry Explanation 


Header specification 


Record sort 
Tag sort 
Address sort 
Index sort 








Decimal number specifying the total length of all key 
fields listed in the Field Specifications (must be the 
maximum for SORTR). 







A or blank, 
D 


Sort processing sequence: ascending or descending. 





This entry specifies the number of bytes for the largest 
record. 


Decimal number 
(SORTR or SORTT 
only) 1-16,383._ eh 





(continued on page) 
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Table 2-3: Fixed Position SORT Specification Summary (continued) 






Field Specifications 








Explanation 








Field specification 
Normal - Key field sequenced as indicated in column 
18 of Header Specification. 


Opposite - Key field sequenced opposite to column 18 
of Header Specification. 


Character type data (8-bit ASCII alphanumeric data 
in key field). 


Zoned ASCIL. 


Digit - use digit value or convert to binary for FOR- 
TRAN IV numbers. | 


Same as D, but with sign leading and separate (that is, 
the first byte of the field is a + or -). 


Same as D, but with sign trailing and separate (that is, 
the last byte of the field is + or -). 


Same as D, but with sign leading overpunched (that is, 
the sign is superimposed on the first byte of the field). 


Packed-decimal data type. 


Binary data type - the key field is in two’s complement 
binary notation. 


Decimal number Location of the first byte of the key field. 

1-16,383 

Decimal number Location of the last (or only) byte in the key field. 
1-16,383 

(not used) i All values are ignored. 


Anything Comments. 


Sample Fixed Position Specification File: 


The following sample shows a header record and field record. Together they 
specify an index sort process on a character key of four bytes starting in 
position 10 of the record, and the output file is to be sorted in descending 
order. 


OCF 1030 


1234567 li SC 


Header Record HSORTI —_ HEADER INDEX SORT ALL DEFAULT. 


Field Record — «FOCO0100013 SW FILELD SPEC ALPHA KEY 





NOTE: 


This sample specification file performs the same sorting process 
as the sample shown for free field position format. 
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2.5.2.2 For VAX-11 SORT (free fields, that is flelds separated by commas): — 
Free fields are formatted in the same sequence as the fixed position fields 
described previously; however, instead of identifying fields with column num- 
bers, commas are used. If you wish to enter blanks or use the default value, 
-you must follow the entry with a comma. 


Header records and field specification records are used in the same manner 
here as they are for the fixed position field records described previously, and 
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the same explanations and legal entries also apply (see Table 2-3). 


Header Records: 


Field | 

Position Function Legal Values 
1 Page number Any number, or blank, or comma, 
2 Line number Any number, or blank, or comma, 
3 Header record ID H, 
4 Sorting process SORT R,LA,T, or blank, or comma 
5 Total key field size Any number, or blank, or comma, 
6 Sorting order A, D, or blank, or comma, 
7 Collating sequence Anything, or comma, 
8 Output key Anything, or comma, 
9 Record length Any number, or blank, or comma, 
10 Comment ! anything, or blank 


Field Specification Records: 


Field 

Position Function Legal Values 
1 Page number See Header 
2 Line number See Header 
3 Field record ID F, 
4 Key sorting order N, O, or blank, or comma, 
5 Key data type B,C,D,1,J,K,P,Z, or blank, or comma, 
6 start position of key Any number, or blank, or comma, 
7 ending position of key Any number, or blank, or comma, 
Ben Anything-ignored, or comma, 
9 comment ! Anything-ignored 
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Sample Free Field Position Specification File: 


The following sample shows a header record and field record. Together they 
specify an index sort process on a character key of four bytes starting in 
position 10 of the record, and the output file is to be sorted in descending 
order. 


Header Record ]+»sH»sSORTI»+++»s!HEADER INDEX SORT ALL DEFAULT EXCEPT 
TYPE 


Field Record |++F+QsCri0+id++!FIELD SPEC ALPHA KEY 4 BYTES POS 10 
el NAL eee ee 


NOTE: 


This sample specification file performs the same sorting process 
as the sample shown for fixed position format. 


2.6 Setting Up the Keys 


When entering the SORT command qualifier /KEY, you must specify 
/KEY=(subqualifiers and values) for each key field by which the records are 
to be sorted. The total size of all key fields must be less than or equal to 255 
bytes, and the maximum number of key fields allowed is ten. 


Before entering the key subqualifiers and values into the SORT command 
string, perform the following steps (1 through 6). See Section 2.4.1 for /KEY= 
specification information. Figure 2-7 provides a flowchart for quick reference 
when setting up keys. 


Step 1 


Each sort key is assigned a precedence number. You may choose to use either 
the default system or the key numbering system. First decide what your key 
fields will be and in what order you want them sorted. Make notes of their 
sequence for use when assigning the precedence number to each. Note, if you 
intend to enter the sort keys into the command string in the order of preced- 
ence you have chosen for your sorting operation, then the NUMBER= 
subqualifier is not necessary. Instead, the default feature will automatically 
assign the first key entered as key number 1 and each subsequent key the next 
higher number. 





Example: 
Primary Q-MK-00020-00 
2nd. : : 
Key NUMBER=n is Key 2nd. Key 3rd. Key 4th.Key 
-not required $ SORT/KEY=(_ )/KEY=(_ )/KEY=(_ )/KEY=(" ) 
(default) 
wo Lo [P| pm] Lo 
Key NUMBER=n is 
required for , 
random order $ SORT/KEY=(NUMBER=2,)/KEY=(NUMBER=1,)/KEY=(NUMBER=4,)/KEY=(NUMBER=3,) 
sort. 


2nd.Key Primary Key 4th. Key 8rd. Key 
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Figure 2-7; Setting Up the Keys 


Make sure to enter keys 
into the SORT command 
string in the correct 
order or .precedence if 
default key numbering 
is used. 


DECIMAL 


PACKED 
ane aa? YES 


NO 


ZONED YES" 


NO 


SPECIFY 
DECIMAL 


STEP 3 
SPECIFY 
LEADING or 
TRAILING SIGN* 


P4 
SPECIFY 
OVERPUNCHED* 
or SEPARATE SIGN 


2-32 












START 


NO 
(default 


YES 





STEP 1 
ASSIGN Make notes of key number 
KEY assignment, starting position, 
NUMBERS and key field size for each key. 








CHARACTER 
(default) 


SPECIFY 
BINARY 


SPECIFY 
PACKED 
DECIMAL 


SPECIFY 


ZONED 





BARRERA Bd A EI TOAA 1 AeA GEL TG TORE Pi i Mca So. “TE tains ae aaa 





STEP 5 

SPECIFY START 
POS and SIZE 
for each key 











NOTE: Data type determines the 
unit of key field size. 


NOTE: Total size of all key fields 
must be less than or equal 
to 255 bytes. 


* indicates default parameter. 






STEP 6 
SPECIFY 
ASCEND” or 
DESCEND ORDER 






Enter these key specifications 
for each key into the SORT 


command string. F-MK-00021-00 
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Step 2 


Before you can enter key size in Step 5, you must first determine what the 
data type of each key field is. Figure 2~8 shows a summary of the data types 
supported. See Appendix C for specific descriptions of the date types. 


Example: 
For decimal data type, specify DECIMAL in the command string. For exam- 


ple: $ SORT/KEY=(POS=1,SIZE=10, DECIMAL). 
Figure 2-8: Recognizing Data Types and Signed Numbers 


1. CHARACTER — 8-bit ASCII coded alphanumeric characters. 
2. BINARY — (for example, 01010101) 


Packed-Decimal String 


POSITIVE NUMBER NEGATIVE NUMBER 

Odd # Even# Odd # Even # 
§4321+ is 4321+ Is §4321- Is 4321- Is 
54321A 04321A §43210 04321D 


First byte in string 


3. DECIMAL — 8-bit ASCII coded decimal digits 0-9 


Leading Numeric String (Most significant byte is signed 12345) 


SIGNED NUMBER UNSIGNED NUMBER 
+ OF -12345 12346 
vw” Separate Numeric Format Overpunched Format ~ 
+12346 +12345 Ils A2345 
ex 2B or 2 Hex 41 
-12346 -12346 ls J2346 
ex 2D Hex 4A 





Trailing Numeric String (Least significant digit is signed 54321) 


SIGNED NUMBER UNSIGNED NUMBER 
§4321+ or - §4321 












Separate Numeric Format Zoned Numeric Format Overpunched Format 

§4321+ §4321+ is 54321 §4321+ is 5432A 
Hex 2B or 20 ex 31 | Hex 41 

§4321- 54321- is §432q §4321- le §432J 


/ Hex 2D\ 7 Hex 71% 7 Hex 4AN 


F-MK-00028-00 
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Step 3 


If data type is decimal, specify the position of the sign. If data type is not 
decimal, proceed to Step 5. 


Examples: 


1. For +12845 or -12345, specify the optional keyword LEADING__SIGN in 
the command string. For example: 


$ SORT/KEY=(POS=1,SIZE=10,DECIMAL: LEAD) 


2. For trailing sign numbers (that is, 12345+ or 12345-), the optional key- 
word TTRAILING__SIGN is not required (TRAILING__SIGN is default). 


Step 4 


For decimal data types, specify if the sign is overpunched (superimposed) or 
separate from the decimal value. 


Examples: 


1. For separate sign (that is, +12345 or -12345), specify the optional keyword 
SEPARATE__SIGN in the command string. For example: 


$ SORT/KEY=(POS=21,SIZE=10+;DECIMAL »LEAD »sSEPA) 


2. For overpunched sign (that is, 5482A or 5432J), the optional keyword 
OVERPUNCHED__SIGN is not required (OVERPUNCHED.__SIGN is 
default). 


Step 5 


You must specify the starting position (first character in the key field) and the 
size for each key. The first character of the record is 1. 


Example: (in this example, key NUMBER= is default, data type is 
CHARACTER). 


$ SORT/KEY=(POS-=:1,SIZE=10 )/KEY=(POS=22,SIZE=8 )/KEY=(POS=42,SIZE=6.)/KEY=(POS=64,SIZE=16.) 


‘80-Character Pear ar ae Soe 
Se j 
1 10 22 29 
bt diet Se 





Key 
4248 —t—<‘is« HS 79 80 
Character / we ee’ eee ys Oe? 
Positions 10-ch. 8~ch. 7-ch. 16-ch. 
key key key key 
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NOTE: 


Key field size can represent either the number of bytes, or 
digits depending on the data type. The chart below describes 
which unit of key field size to use: 


Data Type Size Indicates 

Character Number of characters (bytes) must be less than or equal to 
255. 

Binary Number of bytes must be either 1, 2, or 4. 


1 byte for decimal values in the range of -128 to 127. 


2 bytes for decimal values in the range of -82,768 to 
32,767. 


4 bytes for decimal values in the range of -2,147,483,648 to 
2,147,483,647. 


Decimal Number of digits in the string must be less than or equal to 31. 


The number of bytes in the key field for character, binary, zoned numeric, 
and overpunched is identical to the number of characters or digits. The size of 
leading separate or trailing separate fields is equal to the number of digits 
plus one. The size of packed-decimal fields is equal to (number of digits/2) +1. 


See Appendix C for additional information. 


Step 6 


Specify for each key, whether that key is to be sorted into ascending or 
descending order. Ascending order is default. 


Example: 


To sort the first key in ascending order and the second key in descending 
order, enter the key parameters into the command string as follows: 


$ SORT/KEY=(POS*1LsSTZE=1O)/KEVY=(POS#22 ;STIZE=8 sDESCENDING) 
Now that you have performed Steps 1 through 6 to assemble specifications for 


each key, you are ready to enter these key specifications into the SORT 
command string. 


2.7 Setting Up the Work Files 


SORT automatically assigns two work files to your SYS$DISK device if you 
choose to use the default. The size of these two work files (SORTWORKO and 
SORTWORK1) is determined by SORT from the size of your input file. 
(Note; if no assignment is done, work files are created on SYS$DISK). 
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To assign your work files to a device other than the device your directory is on, 
type: 


$ ASSIGN (device): SORTWORKO 
$ ASSIGN (device): SORTWORKI 


¢ 


$ ASSIGN (device): SORTWORKS 


Example: * ASSIGN DB3: SORTWORK1 


Figure 2-9 illustrates how logical names are assigned to physical devices. 


Figure 2-9: Specifying Work Files. 


WORK FILE # __ Logical Name 


SORTWORKO 
SORTWORK1 
SORTWORK2 


SORTWORK3 
SORTWORK4 A specific physical device code is assigned to a 


SORTWORK5 specific logical name using the ASSIGN, or DE- 


SORTWORK6 FINE commands. 
SORTWORK7 
SORTWORK8 
SORTWORKY9 


SORNDaOAAWD 


Physical Device Codes 


DB: RPO4, RPO5, RPOG Disk 






DM: RKO6 Disk 
Example: ASSIGN O: SORTWORKO 
os Unit 0 
Default is AO 
Controller A 
RPO6 Disk 
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Chapter 3 
Calling SORT from User Programs 


You can use SORT as a set of callable subroutines from your programming 
language. There are two functional interfaces to choose from; the file I/O 
interface and the record I/O interface. Both I/O interfaces share the same set 
of six subroutines, and the same calls are used from all languages. 


This SORT subroutine package consists of six external function calls. Each 
call causes a phase of the SORT program to be performed, and returns a 
status (32-bit) value indicating either success or the failure type of the phase. 
Calls and associated parameters conform to the VAX-11 standard calling 
interface. The calls are: 


Subroutine Name Function 
1. SOR$S$INIT__SORT Initialize scratch files, work area, sorting parameters 
2. SOR$PASS_FILES Pass a file name to SORT 
3. SORSRELEASE__REC Pass a record to SORT 
4, SOR$SORT.__MERGE Initiate sorting and intermediate merging of records 
5. SOR$SRETURN__REC Initiate final merge pass and receive output record from 
SORT 
6. SORSEND__SORT Allow clean up of files and work area to complete the 


sort operation 


3.1 File I/O Interface 


The file I/O interface enables you to specify an input file and an output file to 
SORT. SORT then reads the data from the input file and sorts it into the 
output file. 


For the file I/O interface, use the following four calls in the order listed: 


all Function 
1. SOR$PASS__FILES Pass file specifications 
2. SORSINIT.SORT Initialize work areas 
3. SOR$SSORT._MERGE Sort records 
4, SOR$END__SORT Clean up work areas 


3.2 Record I/O Interface 


The record I/O interface enables you to pass individual data records to SORT. 
SORT orders them, then returns each record in correct order, individually. 


For the record I/O interface, use the following five calls in the order listed: 


Call Function 
1. SOR$INIT__SORT Intialize work areas 
2. SOR$SRELEASE._REC Pass an input record 
3. SOR$SORT_MERGE Sort records 
4. SOR$SRETURN__REC Receive a sorted output record 
5. SORSEND__SORT Clean up work areas 
NOTE: 


Calls 2 and 4 are each repeated for as many times as there are records to be 
sorted. 


3.3 Programming Considerations 
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Any program can use either SORT subroutine package interface, providing 
the language used produces VAX-11 native mode code and supports the fol- 
lowing features. 


e 32-bit integers 

e Longword addresses 

e Call by string descriptors 

e Call by reference 

e Hither CALLS or CALLG (that is, VAX/VMS standard calling sequence) 


e External function calls (each SORT subroutine returns a 32-bit status code) 


Calling SORT from User Programs 


Additional information regarding the VAX/VMS calling standards can be 
found in Appendix C of the VAX-11 Common Run-Time Procedure Library 
Reference Manual. SORT follows the Modular Procedure Standards and uses 
the common Run-Time Library routines to allocate memory and event flags. 
However, SORT is not re-entrant. 


The SORT subroutines are a part of the standard VMS library, therefore to 
use the package a user only has to code the appropriate calls into his program, 
compile or assemble and link. During the linking process the appropriate 
SORT routines will automatically be linked with the user’s program. 


Figure 3-1 summarizes the callable subroutine set. 
Figure 3-1: Subroutine Set Summary 


NOTE: . 


Use the subroutine calls in the order shown. 


Call Function 
1. SOR$PASS_FILES Open the input file and create the output file. 
2. SORS$INIT_SORT Set up the key comparison buffer and validate key 
information. 


Get memory for sorting Initial phase, input and output 
buffers, and set up to read input. 


Create work files and initialize the sort. 


3. SOR$RELEASE__REC Get record from user and build key. 


4. SORSSORT__MERGE Insert record by key into sort tree. 
If sort tree is full, continue; if not, get another record. 


Output records to work files as a number of strings of 
sorted records. 


Output and input until no more records and all records 
are output. 


Read in strings from work file and merge them until 
there are ten or less left in work files. 


5. SORSRETURN REC Set up to output records to user. 
Do final merge pass to output records (not work files) . 
to user. 

6. SOR$SEND__SORT Return memory, close output and input files, and de- 


lete work files. 
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3.3.1 Key Comparisons 


Both Interfaces 


When using either interface, you have the choice of allowing SORT to do key 
comparison to determine the correct order of any two records, or of writing a 
routine of your own that SORT can call to do the key comparisons. 


The advantage of writing your own routine is that you may know a great deal 
more about the nature of the key data and therefore write a routine specifi- 
cally tailored to that particular data. Because SORT does not know anything 
about the key data in advance of receiving it, SORT’s key comparison routine 
must be general in order to handle all types of data. A routine tailored to a 
particular data type or set can therefore be much more efficient, both in space 
and performance. 


If you want to use the SORT key comparison routine, you must provide the 
key definitions in the SOR$INIT.__SORT call. Or, if you want to use your key 
comparison routine with SORT, you must pass the address of your routine’s 
entry point (with parameters) to SORT in the SOR$INIT__SORT call. See 
Section 3.4.3, Definitions, for details. Users can write a program that uses any 
key data type. 


For debugging purposes, it should be noted that the key comparison routine 
may not necessarily be called each time a call is made to SORT. This situa- 
tion can occur with the following calls: 


SORSRELEASE_REC 
SORSSORT_MERGE 
SORS$RETURN_REC 


Record I/O Interface Only 


For record I/O interface, you must set up the key data area before passing the 
record to SORT if SORT is to do the comparisons. 


The key field must be set up with each key physically next to the one before it, 
in order of precedence from left to right. 


For example: 
If the key definitions looked like this: 


Key 1 - Character, Ascending, Pos 1, Size 4. 
Key 2 - Binary, Descending, Pos 15, Size 2. 


Key 3 - Packed, Ascending, Pos 30, Size 4. 


Then, the key area in the user’s program should look like this: 
ABCD45634D 


keyl kéy2 key3 


SORT will handle ascending/descending considerations as long as SORT is 
doing the key comparisons. The user does not have to modify the key data in 
any way. 
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In addition the entire key area must physically preceed and be adjacent to the 
record. For example: 


(KEYAREA) ABCD45634D 
(RECORD) ABCDEFGHIJKLMN46........ 


When passing the record to SORT, the record descriptor must describe the 
entire string including the key area. Therefore, the length of the string is (total 
key length plus record length) and the address is the address of the first byte 
of the key area. 


For record I/O the only valid key types are 1, 2, and 4; character, binary, and 
packed decimal. However, the instruction set provides a set of decimal in- 
structions that allow conversion from all of the other decimal formats to 
packed. Therefore, when you build the key area from your record data you can 
convert the other decimal types to packed, and by doing so, sort on any of the 
nine valid key data types that the file I/O interface accepts. 


When SORT returns the record it will strip off the key data. The length 
returned will be the length of the record alone and the first byte of the output 
buffer will contain the first byte of the record, not the key. 


If you are passing the address of your own key comparison routine to SORT 
and you do not wish to set up the key field preceding the record, you may 
specify a 0 value as the total key size in the call to SOR$INIT__SORT. You 
then pass just the record to SORT. When SORT calls your key comparison 
routine the addresses of the two keys will be the addresses of the first byte of 
each record. 


3.4 Subroutines (Parameters, Definitions, and Valid Returns) 


Each call requires several user supplied parameters. Parameters, parameter 
definitions, and valid returns are provided in the following paragraphs for 
each call. Both symbolic and hexadecimal values are provided for the re- 
turned messages as an aid when debugging. 


All user program value parameters must be passed to SORT using "call by 
reference" (that is, the address of the value in the user’s data area is passed to 
the SORT routine, not the value itself). | 


All file specifications and records are passed to SORT using string descriptors. 
A descriptor is a 2-longword structure of format. 


For example: 


address of string 


= 2 words = 1 longword 





length of string 


=p! 





= 1 longword 
The address of the descriptor is passed to SORT. 


To omit an optional parameter, either leave it null or pass a 0 address in the 
argument list; do not pass the address of a data item with a 0 value. In general 
the meaning of a parameter and its legal values are identical to the equivalent 
parameter in the command line to the utility. 
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3.4.1 SORSINIT__SORT 


Function: Initialize scratch files, work area, and sorting parameters. 


Parameters: Each of the following parameters is numbered to match its defi- 
nition which follows. 


Key buffer address © 

Longest record length (LRL) @ 
File size @ 

Number of work files 

Sort type 0 

Total key size @ 


a eee ae See (ee ES 


Comparison routine address @ 


Notes: @ Mandatory for the file I/O interface and for the record I/O interface 
only if SORT is to do the key compares. 


® Mandatory for the record I/O interface. 


© Needed for the record I/O interface and input from unit record or 
magnetic tape devices in order for SORT to be efficient, but is not 
required. 


® Valid only for the file I/O interface. 


@ Mandatory only if parameter 1 is not present and the user program 
is to do the key compares. 


Definitions: 


1. Set up the key buffer in your user data area. The key buffer describes the 
definition of the keys to be sorted on, and has the following format: 





one word = 1-9 for file I/O interface, and 1, 2, or 4 
for record I/O interface 


one word = 0 or 1 







key type 


key order 





start position one word = 1 to (max record size) 





one word = 1-255 (depends on key type) 


Up to ten of these blocks can be specified in the order of key precedence. 


3-6 Calling SORT from User Programs 


The key buffer must be preceded by a word specifying the number of keys 
specified in the following blocks. For example: 


number of keys 


key type (character) 


Key 1 = key order (ascending) 
= start position in record 
= length of key 
key type (packed—decimal) 
Key 2 key order (ascending) 


start position in record 
length of key in number of digits 





Key Types: 1 = Character 6 = Decimal leading overpunched 
2 = Binary 7 = Decimal leading separate 
3 = Zoned 8 = Decimal trailing overpunched 
9 = 


4 = Packed-decimal 
5 = not used 


Decimal trailing separate 


Key Order: 0 = Ascending 1 = Descending 


When passing the address of the key buffer, pass the address of the word 
with the number of keys. 


Longest record length (LRL) is a decimal number (one word in length) 
indicating the longest record length in bytes not including key size. 


File size (one longword in length) is the value for the input file size in 
blocks. 


Number of work files (one byte in length) is the value of 2 - 10 or 0. 
Sort type (one byte in length) is the value of 1 - 4 as listed: 


1 = Record sort 3 = Index sort 
2 = Tag sort 4 = Address sort 


Total key size (one byte in length) is the value of 1 — 255. 


Address of the user generated key comparison routine. You have the op- 
tion of performing your own key comparisons, and not supplying a key 
definition to SORT. SORT calls your routine at the specified address, and 
with the following parameters: 


1) address of key 1 
2) address of key 2 


SORT expects the following return value: 


-1 if key 1 is less than key 2. 
0 if key 1 is equal to key 2. 
1 if key 1 is greater than key 2. 


NOTE 


Keys must not be modified in any way. 
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Valid Returns: 


Symbolic 
SOR$__SORT__ON 


SOR$_MISS_KEY 
SOR$_BAD__TYPE 
SOR$__BAD__LRL 
SOR$__LRL_—MISS 
SOR$_BAD__FILE 
SOR$__WORK._DEV 


SOR$_VM__FAIL 
SOR$_WS_FAIL 
SOR$_NUM_KEY 


SOR$_KEY__LEN 
SS$_NORMAL 


All RMS error codes 


Hex Value 


1C802C 


108004 
1C806C 
108084 
1C8074 
1C808C 
1C800C 


1C801C 
108024 
1C803C 


1C80AC 
1 
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Meaning 


A sort is already in progress or this call is in 
the wrong sequence. 


No key definition specified. 


An invalid sort process was specified. 


An invalid LRL was specified. 
No LRL was specified and is required. 
An invalid file size. 


Work file device not random access device or 
not local node. 


SORT failed to get needed virtual memory. 
SORT failed to get needed working set size. 


Invalid number of keys specified (must be 
1-10). 


Invalid key length specified. 


Success 


See Chapter 4. 


3.4.2 SORSPASS__FILES 


Function: Pass a file specification to SORT. 


Parameters: Each of the following parameters is numbered to match its defi- 
nition which follows. 


Oo MP AO eT FR Oo DH 


Input file descriptor | 
o 
Output file descriptor 


Output file organizaton 

Output file record format 

Output file bucket size 

Output file block size 9 
Output file maximum record size 
Output file allocation 

Output file file options 


Notes: All output file parameters are specified as for VAX-11 RMS. 


© These parameters are mandatory. 


© These parameters are optional. 


Definitions: 


1. 


Input file descriptor is the string descriptor for the string in ASCII of the 
input file specification. 


Output file descriptor is the string descriptor for the string in ASCII of the 
output file specification. 


Value of output file organization (one byte in length): 


FAB$C__SEQ 
FAB$C__REL 
FAB$C_IDX 


Value of record format for output (one byte in length): 


FAB$C__FIX 
FAB$C__VAR 
FAB$C__VFC 
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ee 


mum RMS file size. 


Value for bucket size (one byte in length) is 1 - 32. 
Value for block size (one word in length) is 18 - 32,767. 
Value for maximum record size (one word in length) is 1 - 16,383. 


Value for output file allocation (one longword in length) is 1 to the maxi- 


9. Value for output file file options (one longword in length) is: see the $F AB 
FOP parameters in the VAX-11 Record Management Services Reference 


Manual. 


Valid Returns: 


Symbolic Hex Value 
SS$__NORMAL 1 
SOR$__SORT__ON 1C802C 
SOR$__VAR__FIX 1C8064 
SOR$_INCONSIS 1C805C 
SOR$__OPENIN 1C109C 
SOR$__OPENOUT 1C10A4 


All RMS error codes 
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Meaning id 
Success 


A sort is already in progress or this call is in 
the wrong sequence. 


Cannot change variable records to fixed 
records. 


Inconsistent data for file. 
Cannot open input file. 
Cannot open output file. 


See Chapter 4. 


3.4.3 SORSRELEASE__REC 

Function: Pass a record to SORT. 

Parameters: Each of the following parameters is numbered to match its defi- 
nition which follows. 


1. Record descriptor 


Notes: Parameter 1 is mandatory. 


Definitions: 


1. Record descriptor is the address of the descriptor for the key and record 
being input to SORT. The length of the record must include the total key 
length plus the total record length. Also, the key field must physically 
immediately precede and adjoin the record, and the descriptor must point 
to the beginning of the key. 


Valid Returns: 


Symbolic Hex Value Meaning 
SS$.-NORMAL 1 Success 
SOR$_SORT__ON 1C802C A sort is already in progress or this call is in 
the wrong sequence. 
SOR$_BAD__LRL 1C8084 Record length is longer than LRL specified. 
~ SOR$_-BAD__ADR 108094 Invalid descriptor address passed. 
SOR$_KEY__LEN 1C80AC Invalid key length specified. 
SOR$_EXTEND 1C80A4 Failed to extend work file. 
SOR$_MAP 1C809C Internal sort map error. 
SOR$__NO__WRK 1C8014 Cannot do sort in memory, need work files. 
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3.4.4 SORSSORT_MERGE 


Function: Initiate sorting and intermediate merging of records. 


Parameters: None. 


Valid Returns: 


Symbolic Hex Value Meaning 
SS$__NORMAL 1 Success 
SOR$_SORT__ON 1C802C A sort is already in progress or this call is in 

the wrong sequence. 

SOR$_EXTEND 1C80A4 Failed to extend work file. 
SOR$_NO.__WRK 3 1C8014 Cannot do sort in memory, need work files. 
SOR$_.MAP | 1C809C Internal sort map error. 
SOR$__READERR 1C10B4 Cannot read a specified input file record. 
SOR$__.WRITEERR 1C10D4 Cannot write a specified output file record. 
SOR$_BADFIELD 10101C Bad data in key field. 
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3.4.5 SORSRETURN__REC 


Function: Initiate final merge pass and receive output record from SORT. 


Parameters: Each of the following parameters is numbered to match its defi- 
nition which follows. 


1. Record descriptor ® 
2. Record size 


Notes: © This parameter is mandatory. 


Definitions: 


1. Record descriptor for the output area that SORT is to place the output 
record into. 


2. The location (one word in length) in which SORT is to place the actual 
size of the record returned. 


Valid Returns: 


Symbolic Hex Value Meaning 
SOR$_.MAP 1C809C Internal sort map error. 
SOR$_EXTEND 1C80A4 Failed to extend work file. 
SS$_NORMAL 1 Success, a record has been returned. 
SS$__ENDOFFILE 870 Success, no more records to return. 
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3.4.6 SORSEND__SORT 


Function: Allow clean up of files and work area to complete the sort opera- 
tion. 


Parameters: None 


Definitions: None 


Valid Returns: 


Symbolic Hex Value Meaning 
SS$__NORMAL 1 Success 
SOR$__CLEAN__UP 1C80B4 Failed to delete work files and reinitialize 


work areas and data areas. 
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3.5 Sample MACRO Program 


*eTITLE TESTSUB 
eIDENT x01,01 


THIS IS A SAMPLE MACRO 
PROGRAM WHICH CALLS 
THE SORT SUBROUTINE 
PACKAGE. THERE IS AN 
EXAMPLE USING EACH 


; 
; 
; 
| INTERFACE. 
; 
; DATA AREA 
4 
FILENAMEIN: “ASCII /ROLOSQ.DAT/ SINPUT FILENAME 
FILENAMEOQUT: ASCII /TEST.TMP/ SOUTPUT FILENAME 
-BLKB 2 ; 
IN_FAB: -BLKB 80 sRMS DATA BLOCKS 
IN_RAB: -BLKB 68 
OUT_FAB: .-BLKB 80 
OUT_RAB: ‘BLKB 68 
FILEIN: LONG 10 SINPUT FILE NAME DESCRIPTOR 
ADDRESS FILENAMEIN 
FILEOUT: “LONG 8 FOUTPUT FILE NAME DESCRIPTOR 
ADDRESS FILENAMEQUT 
KEYBUF : WORD 1 sKEY DEFINITION BUFFER 
KEYTYPE: WORD 1 
KEYORD: WORD 0 
KEYPOS: WORD 1 
KEYSIZ: WORD 10 
INLRL: WORD 80 INPUT RECORD LONGEST LENGTH 
WRKFILE: “LONG 500. sWORK FILE SIZE 
NUMWRK : ‘BYTE 4 SNUMBER OF WORK FILES 
TAGSRT: ‘BYTE 2 STAG SORT 
‘BLKB 2 
KEYAREA: -BLKB = 10 SKEY BUFFER 
RECORDBUF: ‘BLKB 80 SRECORD BUFFER 
RECDESC: “LONG 90 SRECORD DESCRIPTOR 


“ADDRESS KEYAREA 


LONG, STARTING POSITION 1, 


2S «68 SE SS SE RE 


»EXTRN 


FIRST THE FILE I/0 INTERFACE. DO A TAG SORT ON THE FILE ‘RO1OSQ.DAT’ 
INTO THE FILE ‘’TEST.TMP’ USING 4 WORK FILES. KEY IS CHARACTER: 10 BYTES 


SORSPASS. FILES »SORSINIT_SORT »SORSSORT MERGE +SORSEND_SORT »- 


SORSRELEASE_REC »SORSRETURN_REC 


4 


FILEIOs:: 


sENTRY “MERZ eRGeR4OsRO RG OR7> sSAVE REGISTERS 
SDEFAULT ALL OUTPUT OPTIONS 
PUSHAB FILEOQUT sPUSH FILENAME DESCRIPTOR ADDRESS 
PUSHAB FILEIN 
CALLS #2 +SORSPASS_FILES jPASS FILENAMES TO SORT 
BLBC RO +2% TEST FOR ERROR 
PUSHAB TAGSRT sPUSH SORT TYPE 
PUSHAB NUMWRK sPUSH NUMBER OF WORK FILES 
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CLR ~(SP) SDEFAULT LRL AND WORK FILE SIZE 
PUSHAB KEYBUF 3PUSH KEY BUFFER ADDRESS 
CALLS #5 sSORSINIT_-SORT YINITIALIZE THE SORT 
BLBC RO+2$ iSTEST FOR ERROR 
iLET SORT DO COMPARES 
CALLS #0 »sSORSSORT MERGE ISTART SORTING 
BLBC RO 12% sTEST FOR ERROR 
CALLS #0 »SORSEND_SORT ;DO CLEAN UP 
BLBC RO +2% 3TEST FOR ERROR 


NOW TRY THE RECORD 1/0 INTERFACE. RECORDS ARE 80 BYTES LONG, KEY IS 
CHARACTER,» 10 BYTES LONGs STARTING IN POSITION i. WORK FILE SIZE IS 
200 BLOCKS, 


an WS ~2a wee wee wen «a8 


CALLS #0 »OPEN_ INPUT SOPEN USER INPUT AND OUTPUT FILE 
BLBC RO »2% STEST FOR ERROR 
SDEFAULT SORT TYPE AND WORK FILES 
PUSHAB WRKFILE ;PUSH WORK FILE SIZE 
PUSHAB INLRL 3PUSH LRL 
PUSHAB KEYBUF ;PUSH KEY BUFFER ADDRESS 
CALLS #3 ,SORSINIT_SORT SINITIALIZE THE SORT 
BLBC RO »2% iTEST FOR ERROR 
MOV2ZWL #1000+RG SSET UP LOOP INDEX 
1%: CALLS #0 GET RECORD GET RECORD FROM MY FILE 
BLBC RO »2% STEST FOR ERROR 
MOVC3 #10 /RECORDBUF sKEYAREA $SET UP KEY IN KEY BUFFER 
SSORT DOES COMPARES 
PUSHAB RECDESC IPUSH RECORD DESCRIPTOR 
CALLS #1 ,SOR#RELEASE_REC IGIVE RECORD TQ SORT 
BLBC RO ».2% iTEST FOR ERROR 
SOBGTR RG rit 
SSORT DOES COMPARES 
CALLS #0 »,SOR#SORT_MERGE INO MORE RECORDS TO GIVE 
2$: BLBC RO +6 
3s 
PUSHAB INLRL ;PUSH RECORD SIZE LOCATION 
PUSHAB RECDESC 7PUSH RECORD DESCRIPTOR 
CALLS #2 ,SORSRETURN_REC ;GET RECORD BACK 
CMPL RO,»SS$ ENDOFFILE SGOTTEN ALL RECORDS 
BEOL At iYES 
BLBC RO »6% SERROR 
CALLS #0 »PUT..RECORD ;PUT RECORD INTO OUTPUT 
BRB 3S 
4%: CALLS #0 SORSEND_SORT sFINISH UP 
BLBC RO GS ;TEST FOR ERROR 
CALLS #0 ,CLOSE_FILE SCLOSE UP FILES 
MOYL #1+RO SINDICATE SUCCESS 
RET 
6%: CLRL RO SINDICATE FAILURE 
RET 
; 
»END 
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3.6 Sample COBOL-74/VAX Program 


IDENTIFICATION DIVISION, 
PROGRAM-ID. TSTSORT. 
+ 
* THIS IS A SAMPLE COBOL-74/VAX PROGRAM THAT CALLS THE NATIVE 
* SORT SUBROUTINE PACKAGE USING THE RECORD I/0 INTERFACE. IT 
* REQUESTS A RECORD SORT USING A 5 BYTE CHARACTER KEY, 
* 
ENVIRONMENT DIVISION, 
INPUT-OUTPUT SECTION, 
FILE-CONTROL, 

SELECT FILE-IN 

ASSIGN TO "SY", 
SELECT FILE-OUT 
ASSIGN TO "SY", 

DATA DIVISION. 
* 
* ASSIGN FILE DEVICES 
* AND NAMES AND DEFINE INPUT AND OUTPUT RECORD AREAS. 
* 
FILE SECTION. 
FD FILE-IN 

VALUE OF ID IS "SORTIN,DAT" 

LABEL RECORDS ARE STANDARD. 


O1 IN-REC, 
05 IN-1 PIC K(9). 
0S IN-2 PIC K(5). . 


05 IN-3 PIC X(B), 
FD FILE-OUT | 

VALUE OF ID IS "SORTOU.DAT" 

LABEL RECORDS ARE STANDARD. 
O01 OUT-REC PIC X(20), 
* 
* SET UP DATA FOR SORT SUBROUTINE PARAMETERS. 
* 
WORKING-STORAGE SECTION. 


77 END-OF-FILE-SW PIC xX VALUE "O", 
88 END-OF-FILE VALUE "i", 
77 =SHOW-STAT PIC 9(9),. 


* 


* LONGEST RECORD LENGTH» WORK FILE SIZE 
* AND RETURN STATUS VALUES, 


77 ~LRL PIC 99 VALUE 20 COMP, 


77 «=FILE-SIl2 PIC 9(8) VALUE 1 COMP, 

91 SORT-STATUS PIC S9(8) COMP VALUE QO, 
88 SS-NORMAL VALUE 1, 
88 SS-ENDOFFILE VALUE 2160, 

# 

* KEY BUFFER INDICATING ONE 5S BYTE CHARACTER KEY STARTING IN 

* POSITION 10 OF EACH RECORD,» ASCENDING ORDER, 

* 

O1 KEY-BUFFER,. 
O05 KEY-NUMBER PIC 9(4) VALUE 1 COMP, 
OS KEY-TYPE PIC 9(4) COMP VALUE 1, 
O35 KEY-ORDER PIC 9(4) COMP VALUE O, 
05 KEY-START PIC 9(4) COMP VALUE 10, 
O35 KEY-LENGTH PIC 9(4) COMP VALUE 3S. 


* 


* AREA FOR KEY AND RECORD. 
* 
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O01 WK-REC-ALL. 


0S. WK-KEY1 PIC X(5). 
OS WK-REC,. 

10 WK-1 PIC K(9), 

10 WK-2 PIC XK(5)- 

10 WK-3 PIC X(G),. 


PROCEDURE DIVISION. 

MAIN-LOGIC. 

a 

* OPEN THE INPUT AND QUTPUT FILES. THEN INITIALIZE THE SORT 
* SPECIFYING THE KEY DEFINITION+s THE LRL AND WORK FILE SIZE. 
* 


OPEN INPUT FILE-IN 
OUTPUT FILE-OUT. 
CALL "SORSINIT_SORT" USING KEY-BUFFER LRL FILE-SIZ 
GIVING SORT-STATUS,. 
IF NOT SS-NORMAL 
MOVE SORT-STATUS TO SHOW-STAT 
DISPLAY "FAILURE DURING SORSINIT» STATUS WAS "SHOW-STAT 
PERFORM ABORT-JOB. 


READ RECORDS FROM FILE 
EXTRACT THE KEY AND THEN HAND EACH TO SORT. 


* ek ok 


PERFORM RELEASE-RECS UNTIL END-OF-FILE. 


* 


END OF FILE CALL SORT TO FINISH SORTING RECORDS. 


* 


CALL "SORS$SORT_MERGE" GIVING SORT-STATUS. 

IF NOT SS-NORMAL 
MOVE SORT-STATUS TO SHOW-STAT 
DISPLAY "FAILURE DURING SORSMERGE, STATUS WAS " SHOW-STAT 
PERFORM ABORT-JOB. 

MOVE "oO" TO END-OF-FILE-SHW, 


sd 


REQUEST RECORDS BACK FROM SORT UNTIL ALL RECEIVED. 


PERFORM RETURN-RECS UNTIL END-OF-FILE. 


ok 


CALL SORT TO CLEAN UP WORK AREAS. 


CALL "SORSEND SORT" GIVING SORT-STATUS, 

IF NOT SS-NORMAL 
MOVE SORT-STATUS TO SHOW-STAT 
DISPLAY "FAILURE DURING SORSEND;, STATUS WAS " SHOW-STAT 
PERFORM ABORT-JOB, 


CLOSE FILES. 


oe 


CLOSE FILE~IN 
FILE-OUT. 
STOP RUN, 
+ 
* READ RECORDS AND BUILD KEY. 
# 
RELEASE-RECS. 
READ FILE-IN 
AT END 
MOVE "1" TO END-OF-FILE-SH, 
IF NOT END-OF-FILE 
MOVE IN-REC TO WK-REC 
MOVE IN-2 TO WK-KEY1 
CALL "SOR$RELEASE.REC" USING BY DESCRIPTOR WK-REC-ALL 
GIVING SORT-STATUS,. 
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IF NOT SS-NORMAL 
MOVE SORT-STATUS TO SHOW-STAT 
DISPLAY "FAILURE DURING SORSRELEASE, STATUS WAS " SHOW-STAT 
PERFORM ABORT-JOB,. 
* 
* RECEIVE RECORDS AND WRITE THEM OUT. 
% 
RETURN-RECS, 
CALL "SORSRETURN REC" USING BY DESCRIPTOR WK-REC 
BY REFERENCE LRL 
GIVING SORT-STATUS. 
IF SS-ENDOFFILE 
MOVE "1" TO END-OF-FILE-Sh, 
IF NOT END-OF-FILE 
MOVE SPACES TO OQUT-REC 
MOVE WK-REC TO OUT-REC 
WRITE OUT-REC, 
ABORT~-JOB. 
DISPLAY "ABNORMAL END OF JOB", 
CLOSE FILE-IN 
FILE-OUT,. 
STOP RUN, 
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3.7 Sample FORTRAN IV PLUS Program 


INI OIrInininin 


qIaoaI»0>nin oe oe oe De 


oon oocg 


onc 


10 
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PROGRAM CALLSORT 


THIS IS A SAMPLE FORTRAN IV PLUS PROGRAM THAT CALLS THE 
NATIVE SORT SUBROUTINE PACKAGE USING THE FILE I/0 INTERFACE. 
THIS PROGRAM REQUESTS AN INDEX SORT OF FILE ’RO105Q.DAT’ 
INTO THE FILE ‘TEST.TMP’. THE KEY IS AN 80 BYTE CHARACTER 
ASCENDING KEY STARTING IN POSITION ONE OF EACH RECORD. 


DEFINE EXTERNAL FUNCTIONS AND DATA 


CHARACTER#10 INPUTNAME 1LINPUT FILE NAME 
CHARACTER*#8 OUTPUTNAME !OUTPUT FILE NAME 
INTEGER#2 KEYBUF (5S) IKEY DEFINITION BUFFER 
INTEGER#2 NUMWRK !'NUMBER OF WORK FILES 
INTEGER#2 ISRTTYP !'SORT PROCESS 


INTEGER*4 SORSPASS_FILES !'SORT FUNCTION NAMES 

INTEGER#4 SORSINIT_SORT 

INTEGER*#4 SORSSORT MERGE 

INTEGER*#4 SORSEND SORT 

INTEGER#4 ISTATUS I'STORAGE FOR SORT FUNCTION VALUE 


INITIALIZE DATA - FIRST THE FILENAMES THEN THE KEY BUFFER FOR 
ONE 80 BYTE CHARACTER KEY STARTING POSITION 1» 3 WORK FILES 
AND AN INDEX SORT PROCESS 


DATA INPUTNAME ,OUTPUTNAME/ ‘RO10SQ.DAT’ »’TEST.TMP’/ 
DATA KEYBUF sNUMWRK s+ ISRTTYP/1 91 9091 180139 3/ 


CALL THE SORT EACH CALL IS A FUNCTION 


PASS SORT THE FILENAMES 


ISTATUS = SORSPASS_FILES( INPUTNAME »,OUTPUTNAME ) 
IF (.NOT. ISTATUS) GOTO 10 


INITIALIZE WORK AREAS AND KEYS 


ISTATUS = SORSINIT-SORT(KEYBUF ++ sNUMWRK »ISRTTYP) 
IF (.NOT. ISTATUS) GOTO 10 


SORT THE RECORDS 


ISTATUS = SORSSORT_MERGE( ) 
IF (.NOT. ISTATUS) GOTO 10 


CLEAN UP WORK AREAS AND FILES 


ISTATUS = SORSEND_SORT() 
IF (NOT. ISTATUS) GOTO 10 
STOP ‘SORT SUCCESSFUL ’ 
STOP ‘SORT UNSUCCESSFUL ’ 
END 
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Chapter 4 
Error Conditions 


You can encounter error conditions at three operating levels: first with the 
VAX/VMS DCL command interpreter, next with the SORT error messages, 
and last with VAX-11 RMS messages. 


SORT handles two basic types of errors; fatal and warning. Fatal errors (se- 
verity level F) cause SORT to halt processing; warning errors (severity level 
W) cause a warning message to be output and allow sort processing to pro- 
ceed. Errors in both these categories are grouped into three classes: 


e Errors caused by I/O or other system failures. 


e Errors caused by misinformation passed to SORT as a parameter of a su- 
broutine call. 


e Errors caused by invalid data in a key field. 


For the SORT utility, errors of all types and classes are signaled to the sys- 
tem; this signal causes a message to be output. Execution is either stopped or 
continued based on the severity of the error. Execution can be resumed only if 
the severity level is W (that is, code = 0). 


In summary, only invalid data errors and a few RMS errors cause warning 
error messages. System or I/O failures and bad subroutine parameters are 
fatal. For additional information regarding error condition handling, refer to 
the VAX/VMS System Services Reference Manual. 


4.1 Command Interpreter Error Messages 


In interactive mode, when you enter a command line incorrectly, the com- 
mand interpreter issues a descriptive error message telling you what was 
wrong. For example, if you specify more than one parameter for a command 
that accepts a single parameter, you receive the message: 


YODCL-W-MAXPARAM»s maximum Parameter count exceeded 


You must then retype the command line. 


Other error messages may occur during execution of a command. These mes- 
sages can indicate such errors as a nonexistent file or a conflict in qualifiers. 
Not all messages from the system indicate errors; other messages are informa- 
tive, or merely warn you of a particular condition. 


The VAX/VMS system messages have the general format: 
*AAK-L-CODE+ text 


Descriptive comment. 
Shorthand code for the message text. 
Severity Level: 

S = Success 


W = Warning 
E = Error 
F = Fatal 


Mnemonic for the operating system program 
issuing the message. 


Example: 


%4SORT-W-CLOSEOUT:+ error closing output (output file-spec- 
ification) 


Because these messages are descriptive, you can usually understand what you 
need to do differently when you issue the command again. But, if you do not, 
the VAX/VMS Messages and Recovery Procedures Manual lists all the possi- 
ble command interpreter error messages and describes what you can do to 
correct a command interpreter error. 


4.2 SORT Error Messages 
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The following VAX-11 SORT error messages are listed in alphabetic order. 
All SORT error messages have the same format as command interpreter mes- 
sages, that is: 


Z50RT-(severity level)-(code) +s(text). 


Error Conditions 


The following descriptions of error messages observe the following 
conventions: 
e Only the (code), (text) part of the message is shown in the following list. 


e(filespec) indicates a _ file specification. For example: 
DB1:(153,10/ TEST.TMP;3 


e (number) indicates the user entered numeric value. 


e LRL means the longest record length (specified in bytes). 


BAD ADR» invalid descriptor address specified. 


You passed the subroutine package an address for a descriptor, and the 
descriptor was invalid format. Character string descriptors in VAX consist 
of two longwords. The first word of the first longword contains the charac- 
ter string length in bytes. The second longword contains the address of the 
string. 


User Action: See Section 3.4 and check character string format. 


BADFIELD,»+ (filespec,s or field text that is invalid) field in- 
Valid at (number), 


Bad data in key field or command. In this message, (number) indicates 
the record number of the record containing bad data in hex. 


User Action: Check key field data type and the starting positions and 
lengths (See Section 2.6, Setting Up the Keys). 


BADLFILE» file size invalid, 


You specified a negative file size or a zero file size. File size must be 
greater than zero. 


User Action: Specify a file size greater than zero. 


BADLKEY»s invalid Key specification. 


Hither the key field size, position, data type, or order is incorrect within 
the key definition. Positions start at one and cannot be greater than the 
maximum record size. Size must be less than or equal to 255 for character 
data, 1, 2, or 4 for binary data, and less than or equal to 31 for decimal. 


User Action: See Section 2.6, Setting Up the Keys, and check the com- 
mand string key specifications. 
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BAD_LEN>» output record lensth less than 18 bytes for mastape, 


Magnetic tape requires record lengths to be at least 18 bytes and no 
greater than 4096 bytes. 


User Action: See Section 2.4.3, and check your output file block size 
parameters. | 


BAD_LRL»+ input file (filespec), 
Record size greater than specified LRL, 


In reading the input file, SORT encountered a record longer than the 
specified LRL. The record will be truncated to the LRL and sorted. 


User Action: Re-execute SORT with a larger LRL. 


BAD_SPEC» invalid specification file record, 
FIELD: (record specification), 


An incorrect field was. specified in the specification file record. (record 
specification) indicates bad record contents. 


User Action: See descriptions of specification file record formats (Section 
2.5.2) and change field specifications. 


BAD_TYPE+ invalid sort process. 


You passed the subroutine package a sort type code of less than 1 or 
greater than 4 if file I/O or not equal to 1 if record I/O, or an invalid key 
word in command /PROCESS. Legal values are 1-4 for file I/O, nothing 
for record I/O, and RECORD, TAG, INDEX, or ADDRESS for command 
/PROCESS parameter. 


User Action: Specify a different sorting process. 


CLEAN_UP>» failed to reinitialize work area and files. 


SORT was unable to deallocate the extra virtual memory, deassign work 
file channels, or readjust working set size. For the SORT utility, this is a 
warning of little importance. For the SORT subroutine packages, this 
could mean a failure to be able to recall SORT from the same program 
until it has exited. This is an internal error. 


User Action: Exit from the user program before re-executing SORT. 


CLOSEIN» error closing (filesrpec) as inPut. 


An error occurred closing an input file. This message is usually accompa- 
nied by an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 
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CLOSEOQUT>» error closing (filespec) as output. 


An error occurred closing an output file. This message is usually accompa- 
nied by an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the accompanying message. 


EXTEND>+ failed to extend work file. 


SORT failed to extend a user’s temporary work file. Either the device is 
full, or the user does not have extend privilege. 


User Action: See Section 2.7 and reassign work files to a different 
device with more space, and make sure you have extend privilege on that 


directory. 


INCONSIS» inconsistent data in file (filespec). 


If you specified /OVERLAY plus other output file qualifiers, SORT will 
verify that the information in the existing file matches the information 
you provided. If it does not, this error message is reported. Unless you 
specifically want a verification, /OVERLAY should be used without other 


qualifiers. 


User Action: Check the command string output file qualifiers (See Section 
2.4.3). 


IND-OVR» indexed sequential output requires overlay auali- 
fier, 


You specified indexed output file organization and did not specify /OVER- 
LAY. 


User Action: You must create the indexed file first with RMS DEFINE 
utility (or other). The primary key of the file should be the same as the 
sort key for efficiency but is not required to be. Then you must specify 
/OVERLAY in the SORT command string. 


KEYWLEN»s Key length invalid. Key number (number) + size 
(number). 


The key size is incorrect for the data type, or the total key size is greater 
than 255. 


User action: See Section 2.6, Setting Up the Keys, and specify correct key 
field size. Size must be less than or equal to 255 for character data, 1, 2, or 
4 for binary data, and less than or equal to 31 for decimal. Also, only 
ascending or descending order is allowed. 
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LRL_MISS» LRL must be specified, 


If record I/O interface subroutine package is selected, the longest record 
length (LRL) must be passed to SORT in the call. 


User Action: See Section 3.4, and specify LRL. 


MAP;+ failed to map work file. 
This is an internal SORT failure. 


User Action: Verify that the system parameter "maximum process sec- 
tions" has been set up at 10. If it has, then report this failure to a special- 
ist. Otherwise, set that system parameter to 10. 


MISS_KEY>» Key specification missing. 


SORT did not find any key definition in either the command line or 
specification file, or in the parameters to the subroutine package. 


User Action: You must input at least one key definition in one of these 
three areas. 


NOLWRK » need work files cannot do SORT in memory, 


You specified /(WORK-FILES=0 indicating the data would fit in memory, 
but the data was too large. 


User Action: Either increase the working set quota, or allow SORT to use 
two or more work files. 


NUM_KEY» too many Keys specified. 


Up to ten key definitions are allowed. Either too many have been speci- 
fied, or the NUMBER value is wrong. 


User Action: See Section 2.6, Setting Up the Keys, and check your com- 
mand string key field specifications. 


ONE_IN»s only one input file allowed, 
SORT will take only one input file at a time. 


User Action: You can concatenate files of the same organization and 
record format using COPY, and then sort. 


OPENIN: error opening (filesPec) as input 


An input file cannot be opened. This message is usually accompanied by 
an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 
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OPENOUT:s error opening (filespec) as output 


An output file cannot be opened. This message is usually accompanied by 
an RMS message indicating the reason for the failure. 7 


User Action: Take corrective action based on the associated message. 


READERR + error reading (filespec) 


An input file record specified cannot be read. This message is usually 
accompanied by an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


SORT.WON:+ sort already in Progress, 


You tried to call the SORT subroutine package with calls in the wrong 
order, or to recall it before it finished running the previous sort. 


User Action: Reorder the subroutine calls and then re-execute SORT. 


WAR OF IX + cannot change variable length records into fixed 
length, 


You specified variable length input records and requested fixed length 
output. 


User Action:Output records must be variable or controlled in this case. 


VMUPAIL >» failed to get reaunired virtual memory (number). 


SORT could not get the amount of virtual memory required for the sort. 
(number) indicates the number of bytes needed. 


User Action: If the SORT utility is being run, decrease the working set 
quota; if either SORT subroutine package is being run, either decrease the 
quota or return some memory to the system inside the user’s program 


before calling SORT. 


WORK OUDEY >» work file (filespec) 
device specified not random access or not local. 


Work files must be specified for random access devices that are local to the 
CPU the sort is being performed on (that is, not on node in a network). 
Random access devices are disk devices. 


User Action: See Section 2.7, Setting Up the Work Files, and specify the 
correct device. 


Error Conditions 4-7 


WRITEERR:+ error writing (filesprec) 


An output file record cannot be written. This message is usually accompa- 
nied by an RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


WS_FAIL» failed to get reauired working set space (number), 


SORT could not set the required amount of real memory space. A mini- 
mum 75 page working set is needed. (number) indicates number of pages 
available. 


User Action: Increase the working set quota. 
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Listed below, in alphabetic order, are the VAX-11 RMS completion status 
codes. This list includes both symbolic and hexadecimal codes for error mes- 
sages and success messages. These RMS codes are returned to your program 
by the operating system. 


All VAX-11 RMS error messages have the same format as command inter- 
preter messages, that is: 


ZRMS~(severity level)-(code) s(text),. 


For additional information refer to the VAX-11 Record Management Services 
Reference Manual. 


Valid Returns for Error Messages: 


Symbolic Hex Value Meaning 
RMS$_ACC 0001C002 File access error. 
RMS$__ACT 0001825A File activity peecludes operation. 
RMS$__AID 000183F4 Bad area identification number field in allocation XAB. 
RMS$__ALN 000183FC Invalid alignment boundary type in allocation XAB. 
RMS$__ALQ 00018404 Incorrect allocation quantity in allocation XAB; the 


value either exceeds the maximum allowed, or is equal 
to zero for the extend service. 


RMS$__ANI 0001840C Records in a magnetic tape file are not ANSI D format. 
RMS$__AOP 00018414 Invalid allocation option in allocation XAB. 
RMS$.__ATR 0001CO0CC Read error on file header. 

RMS$_ATW 0001C0D4 = Write error on file header. 

RMS$__BKS 0001841C Invalid bucket size in FAB. 


Error Conditions 


Symbolic 


RMS$_BKZ 


RMS$__BLN 
RMS$_BOF 


RMS$_BUG__DDI 


RMS$_.CCR 


RMS$_CDA 
RMS$_CHN 
RMS$__COD 
RMS$_CRE 
RMS$_CUR 


RMS$_DAC 
RMS$_DEL 


RMS$_DEV 
RMS$_DIR 
RMS$_DME 


RMS$_DNA 
RMS$__DNF 
RMS$__DNR 
RMS$__DPE 
RMS$__DVI 

RMS$_ENT 
RMS$__ENV 


RMS$_EOF 
RMS$_ESA 
~RMS$_ESL 

RMS$_ESS 

RMS$_EXP 
RMS$_EXT 
RMS$__FAB 


Hex Value 


00018424 


0001842C 
00018198 


0001843C 


00018494 


0001C0E4 
0001COEC 
000184AC 
0001C00A 
000184B4 


0001C012 
00018262 


000184C4 
000184CC 
000184D4 


000184DC 
0001826A 
00018272 
0001C03A 
000184F4 
0001C01A 
00018724 


0001827A 
000184FC 
00018714 

00018504 

000182C2 
00010022 
0001850C 


Meaning 


Invalid bucket size in the allocation XAB for relative 
file. 


Invalid value in block length field. 


File is already at beginning of the file (backspace opera- 
tion). | 


Invalid default directory. Internal VAX-11 RMS error; 
no recovery possible — contact a software specialist. 


Cannot connect RAB (only one record stream permitted 
for sequential files). 


Cannot deliver AST. 
Channel assignment failure. 
Invalid type code in XAB. 
File create error. 


No current record; operation not immediately preceded 
by a successful get or find service. 


File deaccess error during a close service. 


Record accessed by RFA record access mode has been 
deleted. 


Bad device or inappropriate device type for operation. 
Error in directory name. 


Dynamic memory exhausted; occurs only if the related 
I/O segment in the control region is full and the file is 
either a direct access process permanent file, or the user 
has disallowed the use of the program region for I/O 
buffers to VAX-11 RMS. 


Error detected in the default file specification string. 
Directory not found. 

Device not ready. 

Device positioning error; applies only to magnetic tape. 
Invalid device identification in NAM block. 

Error during file enter service. 


Environment error; the code necessary to support the 
file organization or facility was not selected at system 
generation. 


End of file. 

Invalid expanded string area in NAM block. 
Invalid expanded string length in NAM block. 
Expanded string area too short. 

File expiration date not yet reached. 

File extend error. 


Invalid FAB; block indentifier field incorrect. 
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Symbolic 


RMS$_FAC 


RMS$_FEX 
RMS$_FLK 
RMS$_FNA 
RMS$_FND 
RMS$__FNF 
RMS$_FNM 
RMS$__FOP 
RMS$__FSZ 


RMS$__FUL 
RMS$_IFA 
RMS$_IFI 
RMS$_IMX 


RMS$_IOP 


RMS$_IRC ~ 
RMS$_ISI 
RMS$._KBF 
RMS$_KEY 


RMS$_KSZ 
RMS$_LNE 
RMS$_MBC 


RMS$_MKD 
RMS$_-MRN 
RMS$_MRS 
RMS$__NAM 
RMS$_NEF 


RMS$_-NMF 
RMS$__NOD 
RMS$_ORG 
RMS$_PBF 


Error Conditions 


Hex Value 


00018514 


00018282 
0001828A 
00018524 
0001C02A 
00018292 
0001852C 
0001853C 
00018534 


00018544 
0001C124 
00018564 
0001856C 


00018574 


0001857C 
00018584 
0001858C 
00018594 


000185A4 
000185BC 
00018734 


0001C032 
000185CC 
000185D4 
000185DC 
000185E4 


000182CA 
000185F4 
0001860C 
00018614 


Meaning 


Operation not allowed by the value set in the file access 
field of the FAB. 


File already exists. 

File is locked and therefore not available. 
Invalid file specification string address in FAB. 
Files-11 find function failed. 

File not found. 

Syntax error in file name. 

Invalid file processing options. 


Invalid fixed control area size in FAB (equal to 1 for 
print files). 


Device full; cannot create or extend file. 
Illegal file attributes; file header corrupted. 
Invalid internal file identifier in FAB; must be zero. 


More than one XAB of the same type is present for the 
file. 


Illegal operation attempted: 

1. block I/O when not block I/O access. 

2. record I/O when block I/O access. 

3. rewind of process permanent file. 

4. inappropriate device type or file organization. 


Illegal record in sequential file; invalid count field. 
Invalid internal stream identifier in RAB. 
Invalid key buffer address; not in access limits. 


Invalid record key for random operation to a relative 
file. 


Key size not equal to 4 (relative file). 
Logical name error; resulted in duplicates. 


Invalid multi-block count; must not be greater than 
127. 


Files-11 ACP could not mark file for deletion. 
Illegal value for maximum record number. 
Illegal value for maximum record size. 
Invalid NAM block. 


Attempt to use the put service to a sequential file when 
not positioned to end of file. 


No more files for a search operation. 
Node name error. — 
Illegal file organization. 


Invalid prompt buffer address. 


Symbolic 


RMS$__PLG 
RMS$__PLV 
RMS$__PRV 
RMS$_QUO 
RMS$__RAB 
RMS$__RAC 
RMS$_RAT 
RMS$__RBF 
RMS$__RER 
RMS$_REX 


RMS$_RFA 
RMS$_RFM 
RMS$__RHB 
RMS$_RLF 
RMS$_RLK 
RMS$_RMV 
RMS$_RNF-. 
RMS$__RNL 
RMS$_RPL 
RMS$_RSA 


RMS$_RSL 
RMS$_RSS 


RMS$__RST 
RMS$__RSZ 
RMS$_RTB 
RMS$_SHR 
RMS$__SQO 
RMS$__SYN 
RMS$__SYS 
RMS$__TMO 
RMS$__TYP 
RMS$__UBF 
RMS$__USZ 
RMS$__VER 


Hex Value 


0001861C 
0001872C 
0001829A 
00018634 
0001863C 
00018644 


0001864C_ 


00018654 
0001COF4 
000182A2 


0001865C 
00018664 
0001866C 
00018674 
000182AA 
0001COFC 
000182B2 
000181A0 
00010104 
0001868C 


0001873C 
00018694 


0001869C 
000186A4 
000181A8 
000186B4 
000186C4 
000186D4 
0001C10C 
000181B0 
000186K4 
000186EC 
000186F4 
000186FC 


Meaning | 


Error in file prologue; file is corrupted. 

Prologue version unsupported. 

Privilege violation; access denied. 

Error in quoted string. 

Not a valid RAB; block identifier field incorrect. 
Illegal value in record access mode field of RAB. 
Record attributes invalid in FAB. 

Invalid record address. 

File read error. 


Record already exists; in a random access mode opera- 
tion to a relative file, a record was found in the target 
record cell. 


Invalid record’s file address contained in RAB. 
Illegal record format. 

Invalid record header buffer. 

Invalid related file. 

Record locked by another task. 

Files-11 remove function failed. 

Record not found. 

Record not locked. 

Error while reading prologue. 


Record stream active; an attempt was made to issue a 
record operation request in an asynchronous environ- 
ment to a record stream that has a request outstanding. 


Resultant string length field of NAM block invalid. 


Resultant string area size field of NAM block is too 
small. 


Invalid resultant string area. 
Illegal record size. 

Record too large for user buffer. 
Invalid value in the file sharing field of FAB. 
Operation not sequential. 
Syntax error in file specification. 
Error in system QIO directive. 
Time-out period expired. 

Error in file type. | 

Invalid user record area address. 
Invalid user record area size. 


Error in version number. 
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Symbolic 


RMS$_WER 
RMS$_WLK 
RMS$__WPL 
RMS$_WSF 
RMS$__XAB 


Hex Value 


0001C114 
000182BA 
0001C11C 
0001871C 
0001870C 


Meaning 


File processor write error. 
Device is not write-locked. 
Error while writing prologue. 
Working set full. 

Not a valid XAB. 


Valid Returns for Success Messages: 


RMS$_CONTROLC 
RMS$__CONTROLO 
RMS$_.CONTROLY 
RMS$__CREATED 


RMS$__KFF 

RMS$_NORMAL 
RMS$_OK__ALK 
RMS$__OK__DEL 
RMS$__OK.__RLK 


RMS$__OK__RNF 
RMS$__PENDING 
RMS$__SUC 
RMS$__SUPERSEDE 


Error Conditions 


00010651 
00010609 
00010611 
00010619 


00018031 
00010001 
00018039 
00018041 
00018021 


00018049 
00018009 
00010001 
00010631 


Operation completed under Control C. 
Operation completed under Control O. 
Operation completed under Control Y. 


File was created; not opened; used in conjunction with 
the CIF option. 


Known file found. 

Operation successful (synonym for RMS$.__SUC). 
Record already locked. 

Deleted record accessed correctly. 


Record locked but read anyway; locked set RLK bit in 
ROP field. 


Non-existent record. accessed correctly. 
Asynchronous operation not yet completed. 
Operation successful (synonym for RMS$_NORMAL). 


Created file superseded an existing version. 


Chapter 5 
Improving SORT Efficiency 


Users who have special sorting requirements such as very large files, storage 

media contraints, and processing time restrictions can modify SORT’s behav- 

ior for optimum performance. Your ability to improve SORT’s performance 

depends on your understanding of SORT’s operational characteristics de- 
scribed in this chapter. 


This chapter discusses: 


e How the SORT program functions in each phase of operation, and what 
sequence of events occur during a sort run 


e How a user can improve SORT’s efficiency through the use of tuning 
procedures 


5.1 Functional Description 


The SORT program consists of two basic parts: a control program called the 
utility and a callable subroutine package (see Figure 5-1). The utility directs 
the overall processing. The callable subroutine package serves as a collection 
of subroutines that the utility uses during its processing. You can write your 
own control program to take advantage of SORT’s callable subroutines (see 
Chapter 3). 


There are eight phases of operation in the SORT utility. These are described 
in more detail in Section 5.1.2. A sort run breaks down into three tasks. 


First, SORT reads the command string and the specification file, if present, 
decodes them, and then stores the qualifier values and parameters. Any errors 
in the command string or specification file are reported at this point. 
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Figure 5-1: VAX-11 SORT Architecture, Main Functional Components 


CALLABLE 
UTILILTY SUBROUTINE PACKAGE 


\ ee 


IDENTIFICATION AND 
VERSION MODULE 


SORTING ROUTINES 





STATISTICS HANDLER WORK AREA MANAGER 





SPECIFICATION FILE 
DECODER 










COMMAND 
INTERPRETER 
INTERFACE 


KEY PROCESSING 
ROUTINES 





COMMAND 
STRING 


VAX-11 SORT 
VAX/VMS OPERATING SYSTEM 


DCL 
COMMAND COMMAND _ 


INTERPRETER 





F-MK-00024-00 


5-2 Improving SORT Efficiency 


Second, SORT begins the pre-sort operation. The control program calls 
routines to open and read the input file and establish the keys. Then the 
SORT subroutine package is called to begin the initial sorting process. At this 
point, the amount of available internal storage space becomes important to 
the efficiency of the sort. If that space is not sufficient to hold all the records, 
SORT builds strings of sorted records and transfers them to work files on 
temporary storage devices (disk). The SORT program normally provides for a 
default of two work files. A qualifier in the command string can increase the 
number of work files used. 


Third, SORT rebuilds the intermediate work files into a merged file. If the 
process is tag sort, another subroutine reads the records in the proper 
sequence. The records are then written in the output file. If there are no work 
files to merge because main memory was sufficient to hold all the records, the 
sorted records are written directly into the output file. After the last record is 
written, the control program cleans up the work files and exits; SORT is then 
ready to accept another job. 


5.1.1 Sorting Processes 


All four sorting processes can sort records of fixed or variable length, VFC, or 
any valid VAX-11 RMS. Stream format is not supported. The size of the 
records on a fixed-length format file is determined when the file is created. 
The first word of a variable-length format record contains the size of the 
record in bytes. This first word is used by the file system and is transparent to 
SORT. 


5.1.1.1 Record Sort — Record sort outputs all data records in a specified 
sorted sequence. Each record is kept intact throughout the entire sorting 
process, Since this process moves the whole record, it is relatively slow and 
may require considerable main memory or external storage work space for 
large files. 


5.1.1.2 Tag Sort — Tag sort produces the same kind of output file as record 
sort, but it only handles record pointers and key fields. Since this process 
moves a smaller amount of data than record sort, it may perform a faster sort 
than record sort. The input file must be randomly re-accessed to create the 
entire output file, which may be a lengthy process for large files. 


input Data Files 


A record is usually divided into several logical areas called data fields. The 
data in each field may or may not be relevant to SORT. Each field may be 
interpreted as a record identifier, key data, or general data related to the 
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logical content of the record and not relevant to the sorting process. SORT 
uses record identifiers to distinguish the various types of records in a file. 
SORT uses the key fields in each record to reorder an input file. Any other 
data field in a record may be retained in the output file or ignored by SORT. 


Figure 5-2 shows three different types of input records, each with a different 
format. The record identifiers are the letters in position 1: S means sales 
record, O means order record, and R means restock record. In this case, the 
keys chosen for sorting the sales record types are the "item number code" in 
positions 2 to 7, and the "number of items sold" in positions 8 to 13. The "total 
amount of sale" is an example of a data field not relevant to the sorting 
process. 


If you request a sort in ascending order on the sales records as shown in Figure 
5-2, the sort is based on the item number code first and then on the number of 
each item sold within that item number. In order of decreasing significance, 
the keys are: 


1. Item number 


2. Number of items sold 


Figure 5-2: Sample Record Types 
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Output Data Files 


The output file contains all sales records in the order shown in Table 5-1. 


Table 5-1: Sorted Output File 
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Highest item no. Lowest quantity 





Next higher quantity 





Highest item no. Highest quantity 


5.1.1.3. Address Sort — Address sort produces address files, which consist of 
record’s file addresses (RFAs), beginning at 1, and written in binary words. 
These files can be used as a special index file to access randomly the data in 
the original file. It is possible to maintain only one data file, but several 
different index files as needed. Like tag sort, this process uses the minimum 
amount of data necessary in the sorting process. Once the input phase is 
completed, the input file is not read again. This means that address sort is the 
fastest sorting method of the four SORT types. 


NOTE: 


Do not transfer an address index file to a device that cannot 
handle binary data, such as a printer or terminal. 
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The address sort produces an output file consisting of record indices. Each 
record index occupies one 6—byte record in the output file. Assume that you 
are sorting a file consisting of six records using the address sort process. If the 
sequence of record indices corresponding to the sorted records is 5,1, 6,3,4,2 
then the output file can be represented as shown in Figure 5-3. 


Figure 5-3: Sample Address Sort Output File 
Record’s File Address (RFA) 


| Block Number 





RISE TE 





LOW HIGH BYTE-IN-BLOCK 
RECORD (2 bytes (2 bytes (2 bytes 
NUMBER 16 bits) 16 bits) 16 bits) 
| 1 mi er 4 | cnoes eee 
2 000001 000000 000000 
3 000001 000000 000236 
4 000001 000000 000042 
5 000001 000000 000132 
000026 


6 000001 000000 





Number of Contiguous 
Bytes per Block 


Number of Blocks per File 


Note: 


Byte and Block numbers are shown here in hexadecimal, they are written to the actual output 
file in binary. 


5.1.1.4 Index Sort — Index sort produces an address file consisting of records 
file addresses (RFAs) in binary, and key fields in original form. This makes it 
slightly slower than address sort. During processing this sort handles only the 
RFAs and two forms of the key fields. One form is used for sorting and the 
other is left as it was in the original data. 


Index sort produces an output file consisting of record indices plus keys in 
original form. Each record in the output file consists of a 6-byte record index 
plus the key field. 


NOTE: 


Do not transfer an index sort output file to a device that cannot 
handle binary data, such as a printer or terminal. 
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Assume that you are sorting a file consisting of six records using Index sort 
process, and you are using a key size of four characters (bytes). The sequence 
of record indices corresponding to the sorted record, is 5,1,6,3,4,2 as shown in 
Figure 5-4. 


Figure 5-4: Sample Index Sort Output File 


Record’s File Address (RFA 


Block Number 


LOW HIGH BYTE-IN-BLOCK 
RECORD | (2 bytes (2 bytes (2 bytes 
NUMBER | 16 bits) 16 bits) 


I eee tartan theme ertintensh eminem iam center atinaltiebinnsi ima 2 ee eee 





000001 000162 


000001 000000 
000001 000236 
000001 000042 


000132 


000001 





000026 


000001 


Notes: 


1. ABCD represents the sorting keys in original format. 


2. Byte and Block numbers are shown here in hexadecimal, they are written to the actual 
output file in binary. 


5.1.2 Internal Organization 


SORT operates in eight phases (phase 0 through 7). Figure 5-5 summarizes 
these phases. 


Phase Function 
0 Decode command line and specification file 
1 Initialize SORT 

Get records 

Sort records 

Initialize merge 

Merge records 

Output records 


End SORT 


I oO oOo 6 UD CUD 
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The VAX/VMS command interpreter calls the SORT utility at its main entry 
point and Phase 0 is initiated. The initial process statistics are acquired from 
the system and stored in a table. SORT calls the command interpreter to 
parse and validate the command line. Then SORT validates this information 
and stores it in various tables and buffers. If a specification file is present it is 
opened, the records are read, the information validated and stored in various 
tables and buffers, and the file is closed. Any errors up to this point are 
reported by signaling the command interpreter. SORT opens the input file, 
and creates the output file. 


SORT begins Phase 1. The sorting process is initialized by filling in the key 
comparison information, allocating the space needed for input and output 
buffers and the sort tree, creating the work files and initializing the sort tree. 


Phase 2 begins the sort proper. SORT either reads records from the input file, 
or receives them from the caller. 


At Phase 3, SORT builds the key from the record and inserts each record into 
the tree by key. This process repeats until the sort tree is full or there are no 
more records. SORT then outputs the records to the work files as a variable 
number of strings each of which is a set of sorted records. Each time a record 
is output from the tree a new one is input until there are no more records. The 
rest of the records in the tree are our and that ends the initial sorting phase 
(phases 1 through 3). 


Phase 4 starts SORT’s internal merging operation. The memory is redivided 
at this point for the merge phase into one to ten input buffers and one output 
buffer, depending on the number of initial strings. A different string is read 
into each input buffer and the records are merged together into one string and 
output to a work file. This process is repeated until the total number of strings 
is less than ten. 


Phase 5 performs the final merge pass and outputs the remaining string of 
records, which is the final sorted file, to either the output file or the caller. 


Phase 6 closes the input and output files, closes and deletes the work files, and 
returns the memory. 


Phase 7 acquires the final statistics and prints them, then exits SORT back to 
the VAX/VMS command interpreter. 


Notes: 


1. Phases 0 and 7 are part of the utility only. 


2. The last part of phase 0 (opening the input file and creating the output 
file) and phase 6 are used only by the file I/O subroutine package and the 
utility. 


3. Phases 1 through 5 are used by the utility and both the file I/O and record 
I/O subroutine packages. 
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4, Errors during phases 1 through 6 are signaled to the VAX/VMS command 
interpreter if the utility is running, or returned as a status code to the 
caller if the subroutine package is running. 


5. All signaled errors produce messages at the command interpreter level 
(see Chapter 4). 


Figure 5-5: VAX-11 SORT Operating Phases 


PHASE 0 


DCL SORT Command (via VAX/VMS command interpreter). 
Entry point to SORT. 

Get initial process statistics. 

Call command line processor to decode command line. 

If it was specified, call specification file decoder. 

Open the input file and create the output file. 





PHASE 1 


Set up the key comparison buffer and validate key information. 
Get memory for sorting Initial phase, input and output buffers, and set up to read input. 
Create work files and initialize the sort. 





PHASE 2 


Read or get record from user and build key. 





PHASE 3 


Insert record by key into sort tree. 

Is sort tree full? (YES, continue /NO, go back to phase 2) 

Output records to work files as a number of strings of sorted records. 
Output and Input until end of file and all records are output. 





PHASE 4 


Read in strings from work file and merge them until there are 10 or fewer strings left in the 
work files. 





PHASE 5 


Set up to output records to user or output file. 
Do final merge pass outputting records to user files, not work files. 





PHASE 6 


Delete work files, return memory, close output and input files. 





PHASE 7 


Print statistics and exit. 
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Phases —» 0 | 1,2,3 | 


5.1.3 Buffer Allocation and Work Areas 


The SORT utility and subroutine package are initially linked with a mini- 
mum of space allocated. When SORT is initialized, the work area manager 
assigns as much virtual memory as the process needs, and adjusts the working 
set size to the process maximum. This allows SORT to minimize page faults 
during the sorting, and maximize the order of the merge. At the end of the sort 
operation the limits are restored to the size they were at the entry to SORT, 
returning the additional virtual memory to the system. SORT requires a 
minimum of 75 pages of memory for the working set. 


The VAX/VMS memory management system service, create and map section, 
allows a user to specify that a particular span of virtual addresses in the 
program should be read from and written into a particular set of virtual blocks 
within a file on disk, when referenced or paged-out by the entry of another 
page. The actual I/O to and from the disk is all handled by the pager. SORT 
maps the individual virtual addresses representing the work area onto specific 
blocks within a work file. When a particular buffer is then referenced within 
the work area, the pager automatically brings the correct blocks from the work 
file into real memory, and writes the existing blocks back to the correct place 
in the file. 


5.1.4 Dynamic Memory Usage 


Figure 5-6 shows the total address space used by SORT during each of its 
eight phases of operation. 


Figure 5-6: SORT Dynamic Memory Usage 









ee at et a ee ee ey ee eee ome q 
A= User Limit. r Unused i i Output ] 
B= User Quota that must 1 Portion of 1__ Buffer i 
be greater than or 1 Codeand ! 47 input Butter | 
equal to 75 pages of i Data. I #10 I 
real memory. ! I ay SEG 
TAS= Total Address Space. i ] | i 
VM= Virtual Memory. | | r | 
WS= Working Set. | | | 
: Output I | 
i Buffer | ! i 
TAS=WS+(=B) i | | Same as 
VM(=3+B=3+WS) @ l jy VM= Phases 1,2,3 
VM=3+«WS(=B) IButfers(-—3-WS-B)! 
Tree=1/2WS Input Buffer 
Input Buffer= #1 
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Portion of Code Code and pane 
and Data needed Data 
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5.1.5 I/O Considerations 


The input and output files I/O and the specification file I/O are all performed 
under the control of VAX-11 RMS record I/O facilities. Multi-buffering is 
used together with read ahead on unit record devices to optimize the I/O 
operations. The work files are processed by the VAX/VMS memory manage- 
ment system service, create and map section. 


Various devices can be used for input and output files. Figure 2-1 shows which 
devices are allowed for each of the four sorting techniques. Use Figure 2-1 to 
match the sorting process with the devices that best suit your processing 
environment. Data may be stored in binary, ASCII, decimal, packed or zoned. 


5.2 Tuning Procedure 


All generalized sorts consider several factors such as: the memory environ- 
ment (large, small, virtual memory capability or not); the I/O devices to be 
used for work files and their characteristics (speed, arm movement, seek time, 
public or private units); type of files and data most likely to be sorted (large or 
small files, large or small records and keys, random or ordered partially, 
characters or numbers). 


The algorithm must be very good for the cases occurring most often, and 
reasonable on all other cases. VAX-11 SORT is designed for an environment 
of: fairly large files, virtual memory capability, random access disk devices, 

- public and private, larger random character data files, medium size records 
and keys. 


There are three components of a sort that account for the majority of the 
processing time: 


e The number of key comparisons per record per sort. 
e The number of merge passes needed to complete the sort. 


e The amount of time spent waiting for and/or doing I/O to work files. 


5.2.1 User Performance Considerations 


This section discusses how you can determine the most efficient values for the 
following SORT performance parameters. 


e Working set quota 

e Work file devices 

e Number of work files 
e Type of sort (process) 


e File size 
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° Record size 
e Key size 
e System load 


e System process parameters 


5.2.1.1 Working Set Quota — For SORT to work efficiently the most import- 
ant parameter is the working set quota (or size) the user decides to choose. 
The optimum working set quota is the smallest one for which the data can be 
sorted in memory, that is with 0 merge passes. 


To compute the appropriate working set quota size, perform the following 
procedure: 


Step 1. For any sort, take the size of the key fields added together in bytes. 
Step 2. Then add 20. 


Step 3. If the sorting process is record sort, add the number of bytes in the 
longest record; otherwise add 6. Then multiply by the number of 
records in the file. This is the total amount of data you have in 
bytes. 


Step 4. Divide that number by 512 to get the amount in blocks. 


Step 5. Multiply by 2 to get the size of the working set quota you should 
start with. 


For most larger files the number computed will.be much to large to actually 
use as a quota. In such cases, the largest reasonable size based on the system 
load and scheduling considerations is the correct size to use. An individual 
user’s authorized quota is generally the largest reasonable size for the 
particular system. 


For example: 
To sort a 1000 record file with 80-byte records and a total key field size of 
80 bytes using the record process, compute the following: 
1000 X (80+20+80) = 180,000 bytes of data 
180,000/512 = 352 blocks of data 
352 X 2 = 704 block working set quota 
Answer: start with a working set quota of 700. 
However, if the same type of a file contained 40,000 records, the total amount 
of data would be 14,063 blocks. For most systems a quota of 28,000 blocks 


(pages), or even 14,063 is unacceptable. Here the largest reasonable quota 
should be used; for example 1024 pages. 
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5.2.1.2 Work File Devices — Another important parameter is where the work 
files are placed. The fuller the disk and the more activity on the disk contain- 
ing the work files, the less efficient SORT will be. The optimum configuration 
would be to have each work file, and the input and output file all on separate 
empty disks which are only being used by SORT during the sorting process. 
However, this is seldom possible, so the next best configuration is to place 
work files on available disks having the lowest activity. See Section 2.7, Set- 
ting up the Work Files. 


5.2.1.3 Number of Work Files — Because SORT does not depend on the num- 
ber of work files used to determine the order of the merge like SORT-11, the 
advantage of using more than the default number of work files is limited. 
There are two reasons for using more than the default of two work files: 1) to 
spread the work files between more than two disks and/or 2) to have each 
individual file be a smaller size in order to fit onto a smaller or fuller disk. 


If you are using three or four disks, it will help the sort performance to use 
three or four work files, one on each disk as discussed above. For example, if 
you have a 100,000 block file to sort, using two work files would create two 
150,000 block files. But, using four work files would create four 75,000 block 
files that could be placed on disks with less free space. 


5.2.1.4 Type of Sort — Although the type of sort used is often dictated more 
by functionality required than performance there are significant differences 
between the sorts. 


Address sort is the fastest and uses the least temporary disk space. 


Index sort is only slightly slower than address sort but uses more tempory 
storage. 


Tag sort uses the same temporary storage as address sort, but is significantly 
slower. For large records with small keys it is faster than record sort in smaller 
memory sizes if the file is not large. 


Record sort uses a larger amount of temporary storage and is the slowest. 


5.2.1.5 Using SORT’s Statistics — Analyze the sort statistics (Section 2.2.3) to 
determine how to improve the sort’s performance. The number of records in, 
out, sorted if not all equal indicates that there were input or output errors, or 
that there are null records in the file (that is, the number of records read was 
greater than the number sorted or the number output). This condition can 
also be caused by some records containing invalid data in the key fields (if less 
than ten records are in error SORT will continue, otherwise SORT will stop 
executing). 


Longest record length value is obtained from either RMS or the user and can 
be used to make sure the RMS value is correct. 
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The multi block and buffer counts indicate the amount of I/O optimization on 
the input and output file. The larger the working set quota the more optimiza- 
tion possible. No optimization would show all these counts as 1. This should 
not occur unless the file is huge compared to the working set quota. If it does, 
raise the quota if possible. 


The order of the merge is the number, less one, of merge buffers that the 
working set is divided into for the merge phase. 


Number of merge passes and the number of Initial runs shows you how close 
the data is to fitting in memory. The higher these numbers are, particularly 
the number of passes, the longer SORT takes and the further away the work- 
ing set size is from containing the data. 


Virtual memory added is the amount of virtual memory SORT used for the 
data. 


Elapsed time is the total wall clock time in hours, minutes, seconds, and 1/100 
seconds from start to end for the sort run. 


The total of the two I/O counts are the number of disk hits to get and write data 
and these will be higher if the multi block and buffer counts are lower. The 
lower the better. 


CPU time is the time spent actually processing data minus all I/O time. The 
closer to the elapsed time the better optimization you are seeing in I/O. 


Page faults are also a good indication of how well the data did or did not fit 
into memory. The higher the number of page faults, the less efficient the sort 
iS. 


5.2.2 System Manager Performance Considerations 


The system manager can determine the following SORT performance parame- 
ter values based on the overall system usage: number of users, types of process 
most commonly run, and the amount of real memory available. 


e System per process working set quota (WSMAX) 

e System per process virtual page count (VIRTUALPAGECNT) 

e System per process section count (PROCSECTCNT) 

e System modified page writer cluster factor (MPW_-WRTCLUSTER) 


The values recommended are based solely on sort considerations; it is up to 
the system manager to integrate other system considerations with these in 
determining the appropriate final values. 
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5.2.2.1 Working Set Quota — The maximum for this value should be set to the 
largest size any sort job would ever require. For very large files, working sets of 
500 to 1000 pages are not at all unreasonable, provided the system has enough 
physical memory to accommodate them. Individual maximums, to prevent 
users from monopolizing real memory, can be set on a per user basis by using 
the authorization file. For information on how to determine an appropriate 
working set for a particular sort job see Section 5.2.1.1. The general rule is, the 
smaller the working set, relative to the files to be sorted, the slower the sort. 


5.2.2.2 - Virtual Page Count — For this parameter the current value as well as 
the maximum value should be set to a minimum of 3 to 4 times the value of 
the working set quota maximum. When SORT initially starts executing it will 
request 2 and 1/2 to 3 times the working set quota of virtual memory from the 
system. If this value is too low SORT will be unable to run in certain cases. 


5.2.2.3 Process Section Count — For working set quota maximums of 500 or 
less this parameter may stay at a minimum level. However, for working set 
quotas greater than 500 to 1000 a current value of 10 or greater is necessary. If 
this parameter is set too low, SORT will be unable to run in larger working 
sets due to internal mapping failures. The value should be increased as the 
working set quota maximum increases. 


5.2.2.4 Modified Page Writer Cluster Factor — The value of this parameter will 
never cause SORT to fail, however it can cause a large difference in perform- 
ance. For any larger sorts (that is, using working sets of 250 pages or greater) 
the larger this parameter, the better. Values of 64 and up are not too large. Be 
sure to adjust MPW__HILIM and MPW__LOLIMIT accordingly. For more 
information refer to the SYSGEN procedures in the VAX-11 Software Instal- 
lation Guide. 
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Glossary 


Aiphanumeric Characters 
The entire set of 128 ASCII characters (see Appendix B). 


ASCil Character Set 


The set of 128 eight-bit American Standard Code for Information Interchange charac- 
ters (see Appendix B). 


Batch 
A mode of processing in which all commands to be executed by the operating system 
and, optionally, data to be used as input to the commands are placed in a file or 
punched onto cards and submitted to the system for execution. 

BLISS 
A high-level system implementation programming language. VAX-11 SORT is writ- 
ten in BLISS. 

Block 
The smallest addressable unit of data that the specified device can transfer in an I/O 
operation (512 contiguous bytes for most disk devices). 

Bucket 
See File Bucket. 

Buffer 
A temporary data storage area in a process address space used when performing input 
or output operations. 

Byte | 
The smallest addressable unit of information; eight bits. For example, an ASCII 
character requires a single byte (see Appendix C for further definitions). 

Call 
The operation of invoking a procedure. 

Caller 


The procedure that invoked this procedure by a Call. At the time of procedure 
invocation, the invoking procedure is said to be the caller, and the invoked procedure 
is the callee. Contrast with User. 
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Character 


The smallest addressable unit of usable data (byte). It is also a single letter, numeral, 
punctuation mark, or other symbol (such as $ or %), and is represented within the 
computer as a unique combination of bits. Typically, a character code consists of 
eight bits. 


Character String Descriptor 


A quadword data structure used for describing character data (strings). The first 
word of the quadword contains the length of the character string. The second word 
can contain type information. The remaining longword contains the address of the 


string. 


CPU 
The Central Processor Unit portion of a computer system. 


Collating Sequence 


The order into which characters are sorted based upon numeric values assigned to 
each. 


Command 


An instruction, generally an English word, typed by the user at a terminal or in- 
cluded in a command. file, which requests the software monitoring a terminal or 
reading a command file to perform some well-defined activity. For example, typing 
the SORT command request the system to invoke the SORT utility. 


Command File 
A file containing command strings. See also Command Procedure. 


Command Interpreter 


Procedure-based system code that executes in supervisor mode in the context of a 
process to receive, syntax check, and parse commands typed by the user at a terminal 
or submitted in a command file. 


Command Parameter 


The positional operand of a command delimited by spaces, such as a file specifica- 
tion, option, or constant. 


Command Procedure 


A file containing commands and data that the command interpreter can accept in 
lieu of the user typing the commands individually on a terminal. 
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Command String 


A line (or set of continued lines), normally terminated by typing the carriage return 
key, containing a command and, optionally, information modifying the command. A 
complete command string consists of a command, its qualifiers, if any, and its 
parameters (file specifications, for example), if any, and their qualifiers, if any. 


Compatibility Mode 


A mode of execution that enables the central processor to execute non-privileged 
PDP-11 instructions. The operating system supports compatibility mode execution 
by providing an RSX-11M programming environment for an RSX-11M task image. 
The operating system compatibility mode procedures reside in control region of the 
process executing a compatibility mode image. The procedures intercept calls to the 
RSX-11M executive and convert them to the appropriate operating system func- 
tions. 


Contiguous Blocks 
Physically adjacent and/or consecutively numbered blocks of data. 


Data File Record 
A record containing user data. 


Data Structure 


Any table, list, array, queue, or tree whose format and access conventions are well 
defined for reference by one or more images. 


Data Type 


In general, the way in which bits are grouped and interpreted. In reference to the 
processor instructions, the data type of an operand identifies the size of the operand 
and the significance of the bits in the operand. Operand data types include: byte, 
word, longword, and quad-word integer, floating and double floating, character 
string, packed decimal string, and variable-length bit field (see Appendix C). 


DCL 


Digital Command Language (DCL) is a set of English- like statements that a user 
types to initiate and control system operations. 


Default 


An assumed value supplied to the system when a command qualifier does not specifi- 
cally override the normal command function; fields in a file specification that the 
system fills in when the specification is not complete. 


Descriptor 
See Character String Descriptor. 
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Device 


The general name for any physical terminus or link connected to the processor that is 
capable of receiving, storing, or transmitting data. Card readers, line printers, and 
terminals are examples of record-oriented devices. Magnetic tape devices and disk 
devices are examples of mass storage devices. Terminal line interfaces and interpro- 
cessor links are examples -of communications devices. 


Directory 


A file used to locate files on a volume that contains a list of file names (including 
extension and version number) and their unique internal identifications. 


Directory Name 


The field in a file specification that identifies the directory file in which a file is 
listed. The directory name is enclosed in brackets ({] or <>). 


Field 
A logically distinguishable area within a record. Usually a logical unit of data. 


File 


A logically related collection of data on a volume such as disk or magnetic tape. A file 
can be referenced by a name assigned by the user. A file normally consists of one or 
more logical records. | 


File Bucket 


Within the RMS Relative File organization, a bucket is a storage structure of one to 
32 blocks of data. 


File Header 


A block in the index file describing a file on a FILES-11 disk structure. The file 
header identifies the locations of the file’s extents. There is a file header for every file 
on the disk. 


File Organization 


The particular file structure used to record the data constituting a file on a mass 
storage medium. RMS file organizations are: Sequential, Relative, and Indexed. 


File Prologue 


The first block in a relative or indexed file which contains header information for the 
file. 


File Specification 


A unique name for a file on a mass storage medium. It identifies the node, the device, 
the directory name, the file name, and the version number under which a file is stored 
(see Appendix D for additional information). 
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Flie Structure 


The way in which the blocks forming a file are distributed on a disk or magnetic tape 
to provide a physical accessing technique suitable for the way the data in the file is 
processed. 


File System 
A method of recording, cataloging, and accessing files on a volume. 


File Type 


The field in a file specification that is preceded by a period or dot(.) and consists of a 
zero-to three-character type identification. By convention, the type identifies a gen- 
eric class of files that have the same use or characteristics, such as ASCII text files, 
binary object files, etc. 


Files—11 
The standard physical disk structure used by VAX-11 RMS. 


Filespec 
File Specification that uniquely identifies a file by physical location (see Appendix 
D). 

File, input 
See Input File. 


File, Output 
See Output File. 


File, Work 
See Work File. 


Fixed Control Area 


An area associated with a variable length record available for controlling or assisting 
record access operations. Typical uses include line numbers and printer format con- 
trol information. 


Fixed Position Field 


An area associated with character position (or column numbers). Used in SORT-11 
Specification Files. | 


Fixed Length Record Format 
A file format in which all records have the same length. 
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Format 
The arrangement of any record or file; the order in which fields reside in a record. 


Free Fields 
Logically positioned fields separated by commas. Contrast with fixed position fields. 


Home Block 


A block in the index file that contains the volume identification, such as volume label 
and protection. 


image 


A file consisting of procedures and data that have been bound together by the linker. 
There are three types of images: Executable, Shareable, and System. 


indexed File Organization 


A file organization in which a file contains records and a primary key index (and 
optionally one or more alternate key indices) used to process the records sequentially 
by index or randomly by index. 


index File 


The file on a Files-11 volume that contains the access information for all files on the 
volume and enables the operating system to identify and access the volume. 


Index File Bit Map 


A table in the index file of a Files-11 volume that indicates which file headers are in 
use. 7 


Index File Record 
A record of file system data that is invisible to the user. 


Input File 


The file containing the records you wish to sort. 


Key, Key Field 


The data field containing the values chosen from a record to control the sort (see 
section 2.6). 


Key, Major 


The most important field in the total key. If you were sorting a list by department, 
salary and name, department would be the major key. 
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Key, Minor 


The least significant field in the total key. In the preceding example name is the 
minor key. 


Library 
A collection of commonly used files. 


Line 


In this document, a line generally refers to a line in the SORT specifications form or a 
record in the specification file. 


Logical Name 


A user-specified name for any portion or all of a file specification. For example, the 
logical name INPUT can be assigned to a terminal device from which a program 
reads data entered by a user. Logical name assignments are maintained in logical 
name tables for each process, each group, and the system. A logical name can be 
created and assigned a value permanently or dynamically. 


Longword 
Four contiguous bytes (32 bits) starting on an addressable byte boundary (see Appen- 
dix C). 

LRL 


Longest Record Length (LRL) specified in bytes. 


Merge 


A process by which two or more ordered groups of records are put together record-by- 
record into a single identically ordered group. 


Native Mode 


The processor’s execution mode, in which the programmed instructions are inter- 
preted as byte-aligned, variable length instructions that operate on byte, word, long- 
word, quadword integer, floating and double floating, character string, packed deci- 
mal, and variable length bit field data. The instruction execution mode other than 
compatibility mode. 


Node 


An individual computer system in a network. 
Output File 


The file created by running SORT. The output file may be either a data file or an 
address file. 
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Page 


1). A set of 512. contiguous byte locations used as the unit of memory mapping and 
protection. 2). The data between the beginning of file and a page marker, between 
two markers, or between a marker and the end of a file. 


Page Fault 


An exception generated by a reference to a page which is not mapped into a working 
set. 


Pager 


A set of kernel mode procedures that executes as the result of a page fault. The pager 
makes the page for which the fault occurred available in physical memory so that the 
image can continue execution. The pager and the image activator provide part of the 
operating system’s memory management functions. 


Paging 


The action of bringing pages of an executing process into physical memory when 
referenced. When a process executes, all of its pages are said to reside in virtual 
memory. Only the actively used pages, however, need to reside in physical memory. 
In this system, a process is paged only when it references more pages than it is 
allowed to have in its working set. When a process refers to a page not in its working 
set, a page fault occurs. This causes the operating system’s pager to read in the 
referenced page fault if it is on disk (and optionally, other related pages depending on 
a cluster factor), replacing the least recently faulted pages as needed. This system 
only pages a process against itself. 


Packed Decimal 


A method for compact storage of numeric data; two digits are stored in each 8-bit 
byte and the sign resides in the last byte of the low-order digit. 


Parse 
To break down into individual parts from a whole. 


Physical Memory 
The memory modules contained within the CPU. Also called main memory. 


Procedure 


A routine that follows the VAX-11 calling sequence standard. A procedure may 
return values via the argument list and/or the standard value return registers. Con- 
trast with routine. 


Process 


The basic entity scheduled by the system software that provides the context in which 
an image executes. A process consists of an address space and both hardware and 
software context. 
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Program 


A program is the basic entity that is executed by the processor. Each program con- 
sists of a set of procedures and its execution represents a distinct activity that is 
potentially concurrent with others in the system. 


Prologue 
See File Prologue. 


Quadword 


Eight contiguous bytes (64 bits) starting on an addressable byte boundary. See Ap- 
pendix C. 


Qualifier 


A portion of a command string that modifies a command verb or command parame- 
ter by selecting one of several options. A qualifier, if present, follows the command 

verb or parameter to which it applies and is in the format: "/qualifier=option". For 
example, in the command string "PRINT filename/ COPIES=3", the COPIES quali- 
fier indicates that the user wants three copies of a given file printed. 


Random access by record’s file address 


The retrieval of a record by its unique address, which is provided to the program by 
RMS. The method of access can be used to randomly access a sequentially organized 
file containing variable length records. 


Random access by relative record number 


The retrieval or storage of a record by specifying its position relative to the beginning 
of the file. 


Real Memory 
See Physical Memory. 


Record 
The unit of information in a file; a group of related fields treated as a logical unit. 


Record Cell 
A fixed length area in a relatively organized file that is used to contain one record. 


Record Management Services (RMS) 


A set of system procedures in the operating system that are called by programs to 
process files and records within files. RMS allows programs to issue GET and PUT 
requests at the record level (record I/O) as well as read and write blocks (block I/O). 
RMS is an integral part of the system software. RMS procedures run in executive 
mode. 
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Record-oriented Device 


A device such as a terminal, line printer, or card reader, on which the largest unit of 
data that a program can access is the device’s physical record. 


Record’s File Address (RFA) 


The unique address of a record in a file that allows records to be accessed randomly 
regardless of file organization. 


Record, Data File 
See Data File Record. 


Record, Field Specification 
See Section 2.5.2 


Record, Header 
See Section 2.5.2 


Record, Index File 
See Index File Record. 


Relative File Organization 


A file organization in which the file contains fixed length record cells. Each cell is 
assigned a consecutive number that represents its position relative to the beginning of 
the file. Records within each cell can be the same length or smaller than the cell. 
Relative file organization permits sequential record access, random record access by 
record number, and random record access by record’s file address. 


RMS 
See Record Management Services (RMS). 


Routine 


A sequence of instructions that performs a well defined action. It may have multiple 
entry points. For example, the SIN routine has SIN and COS entry points. A routine 
that follows the VAX-11 calling sequence standard is termed a procedure. 


Sequential File Organization 


A file organization in which records appear in the order in which they were originally 
written. The records can be fixed length or variable length. Although one does not 
speak of record cells with sequentially organized files, for purposes of comparison 
with relatively organized files one can say that the record itself is the same as its 
record cell, and its record number is the same as its relative cell number. Sequential 
file organization permits sequential record access and random record access by 
record’s file address. Sequential file organization with fixed length records also per- 
mits random access by relative record number. 
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SORT Utility 


A processing program that can be used to sort records by keys into a prescribed 
sequence. To segregate items into groups according to some definite rules. 


Sort Tree J 
A data structure used to keep order of records by sort. 


Subroutine 


A procedure that does not return a known value in the value registers. If values are 
returned, they are returned via the argument list. By convention, the function "value" 
is unpredictable. 


System Device 
The device on which the Executive resides. 


Terminal 


The general name for those peripheral devices that have keyboards and video screen 
or printers. Under program control, a terminal enables people to type commands and 
data on a keyboard and receive messages on a video screen or printer. Examples of 
terminals are the LA36 DECwriter (hard-copy terminal) and the VT52 video display 
terminal (soft-copy terminal). 


Unit Record Device 
See Record-oriented Device. 


User 


The person who is directly using the computer, either via terminal or batch input. 
Contrast with Caller. 


Varlable-length Record 
A record format in which records need not be the same length. 


Variable with fixed-length control (VFC) record 


A record format in which records of variable length contain an additional fixed-length 
control area. The control area may be used to contain file line numbers and/or print 
format control characters. : 7 


Virtual Address 


A 32-bit integer identifying a byte "location" in virtual address space. The memory 
management hardware translates a virtual address to a physical address. The term 
virtual address may also refer to the address used to identify a virtual block on a mass 
storage device. 
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Virtual Memory 


The set of storage locations in physical memory and on disk that are referred to by 
virtual addresses. From the programmer’s viewpoint, the secondary storage locations 
appear to be locations in physical memory. The size of virtual memory in any system 
depends on the amount of physical memory available and the amount of disk storage 
used for non-resident virtual memory. 


Volume 
A mass storage medium such as a disk pack or reel of magnetic tape. 


Wild card 


The asterisk character when used as a substitute parameter in file specification 
indicates "all" for a given field. 


Word 


Two contiguous bytes (16 bits) starting on an addressable byte boundary (see Appen- 
dix C). 


Work File 


A collection of sorted records created during the processing cycle and released after 
the sort is finished. (Sometimes called Scratch Files.) 


Working Set 


The set of pages in process address space to which an executing process can refer 
without incurring a page fault. The working set must be resident in memory for the 
process to execute. The remaining pages of that process, if any, are either in memory 
and not in the process working set or they are on secondary storage. 


Zoned Numeric Format 


A specific ASCII coded decimal data type where the number sign and the least 
significant digit are combined into a single hexadecimal code (see Appendix C). 
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Appendix A 
Octal/Hexadecimal/Decimal Conversion 


A.1 


Octal/Decimal Conversion 


To convert a number from octal to decimal, locate in each column of the table 
the decimal equivalent for the octal digit in that position. Add the decimal 
equivalents to obtain the decimal number. 


To convert a decimal number to octal: 


1. locate the largest decimal value in the table that will fit into the decimal 
number to be converted, 


2. note its octal equivalent and column position, 


3. find the decimal remainder. 


Repeat the process on each remainder. When the remainder is 0, all digits will 
have been generated. 


32,768 4,096 
65,536 8,192 


98,304 12,228 
31,072 16,384 
163,840 20,480 
169,608 24,576 
229,376 28,672 


I nn oo f}§ CF PO KH SO 





A.2 Powers of 2 and 16 


Powers of 2 


Powers of 16 


2**n n 16**n n 
256 8 1 0 

512 9 16 1 
1024 #10 256 2 
2048 #8ii1 4096 3 
4096 12 65536 4 
8192 13 1048576 5 
16384 14 16777216 6 
32768 15 268435456 7 
655386 16 4294967296 8 
181072 =17 68719476736 9 
262144 18 1099511627776 10 
524288 19 17592186044416 = 11 
1048576 20 281474976710656 12 
2094304 21 4503599627370496 13 
4194304 22 72057594037927936 14 
8388608 23 1152921504606846976 15 


16777216 =. 24 


A.3 Hexadecimal to Decimal Conversion 


For each integer position of the hexadecimal value, locate the corresponding 
column integer and record its decimal equivalent in the conversion table A.5. 
Add the decimal equivalent to obtain the decimal value. 


Example: 
DOSQ0ADO (16) = (10) 
DQdoOOdOO = 9,489,660 ,928 
SOOO = S22 ,880 
AOO = 270960 
DO = 208 
DOS00AaDO = 39+/494,904;576 


A.4 Decimal to Hexadecimal Conversion 
1. Locate in the conversion table A.5 the largest decimal value that does not 
exceed the decimal number to be converted. 


2. Record the hexadecimal equivalent followed by the number of zeros (0) 
that corresponds to the integer column minus one. 


3. Subtract the table decimal value from. the decimal number to be 
converted. | 


4. Repeat steps 1-3 until the subtraction balance equals zero (0). Add the 
hexadecimal equivalents to obtain the hexadecimal value. 


A-2 Octal/Hexadecimal/Decimal Conversion 


Example: 


22/466 (10) = ?(16) 
2£9+480 = $000 221466 
1+792 = 7OQ ~2£9 +480 
192 = CO jj <eitedwiadicie 
Fi = 2 1,986 
moe ome me a - 1,792 
22 +466 sa 4 Oe eT ee ea 
194 
- i92 
2 


A.5 Hexadecimal Integer Columns 


8 7 6 ° 4. 3 2 1 
HEX DEC HEX DEC HEX DEC HEX 'DEC HEX DEC HEX DEC HEX DEC HEX DEC 
0 0 O 0 O 0 0 0 0 0 O 0 0 0 O 0 
1 268,435,456 = 1 16,777,216 1 1,048,576 = 1 65,5386 = 1 4,096 1 256 = 1 16 1 1 
2 536,870,912 2 33,554,432 2 2,097,152 2 131,072 2 8,192 2 5122 32.2 2 
3 805,306,368 3 50,331,648 3 3,145,728 3 196,608 3 12,288 893 768 «3 48 3 3 
4 1,073,741,824 4 67,108,864 4 4,194,304 4 262,144 4 16,384 4 1,024 4 64 4 4 
5 1,342,177,280 5 83,886,080 5 5,242,880 5 327,680 5 20,480 5 1,280 5 80 5 5 
6 1,610,612,736 6 100,663,296 6 6,291,456 6 393,216 6 24,576 36 1,536 6 96 866 6 
7 1,879,048,192 7 117,440,512 7 7,340,032 7 458,752 7 28,672 7 1,792 7 112. 7 7 
8 2,147,483,643 8 134,217,728 8 8,338,608 8 524,288 8 32,768 8 2,048 = 8 128 868 8 
9 2,415,919,104 9 150,994,944 9 9,437,184 9 589,824 9 36,864 9 2,304 9 144 9 9 
A 2,684,354,560 A 167,772,160 A 10,485,760 A . 655,360 A 40,960 A 2,560 A 160 A 10 
B 2,952,790,016 B 184,549,376 B 11,534,336 B 720,896 B 45,056 B 2,916 B 176 +B 11 
C 3,221,225,472 C 201,326,592 C 12,582,912 C 786,432 C 49,152 C 3,072 C 192 C 12 
D 3,489,660,928 D 218,103,808 D 13,631,488 D 851,968 D 53,248 D 3,328 D 208 =D 13 
iE 3,758,096,384 E 234,881,024 E 14,680,064 E 917,504 E 57,344 3,084 FE 224 Ek 14 
F 4,026,531,840 F 251,658,240 F 15,728,640 F 983,040 F 61,440 F 3,840 F 240 +F 15 


| 


BYTE 


\ WORD WORD / 


LONGWORD 
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Appendix B 
The ASCIll Character Set Collating Sequence 


ASCII 














ASCII 
ASCII Hexadecimal 8-Bit | ASCII Hexadecimal §8-Bit 
Character Number Octal Decimal Character Number Octal Decimal 
NUL 00 000 0 FS 1C 034 28 
SOH 01 001 1 GS 1D 035 29 
STX 02 002 2 RS 1E 036 30 
ETX 03 003 3 US 1F 037 31 
EOT 04 004 4 SP 20 040 32 
ENQ 05 005 5 ! 21 041 33 
ACK 06 006 6 ’ 22 042 34 
BEL 07 007 7 # 23 043 35 
BS 08 010 8 $ 24 044 36 
HT 09 011 9 % 25 045 37 
LF 0A 012 10 & 26 046 38 
VT 0B 013 11 27 047 39 
FF 0C 014 12 ( 28 050 40 
CR 0D 015 13 ) 29 051 41 
SO OE 016 14 si 2A 052 42 
SI OF 017 15 + 2B 053 43 
DLE 10 020 16 2C 054 44 
DCi 11 021 17 - 2D 055 45 
DC2 - 12 022 18 2E 056 46 
DC3 13 023 29 / 2F 057 47 
DC4 14 024 20 0 30 060 48 
NAK 15 025 21 1 3l 061 49 
SYN 16 026 22 2 32 062 50 
ETB 17 027 23 3 33 063 51 
CAN 18 030 24 4 34 064 52 
EM 19 031 25 5 35 065 53 
SUB 1A 032 26 6 36 066 54 
ESC 1B 033 27 d 37 067 55 


(continued on next page) 
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ASCII Hexadecimal 8-Bit ASCII Hexadecimal 8-Bit 
Character Number Octal Decimal | Character _ Number _ Octal - Decimal : 
s ~38—i(“‘<‘itt~|}!ClCC@C 6c 134 92 
9 39 071 57 5D 135 93 
3A 072 58 A 5E 136 94 
: 3B 073 59 ae 5F 137 95 
< 3C 074 60 60 140 96 
= 3D 075 61 a 61 141 97 
> 3E 076 62 b 62 142 98 
3F 077 63 c 63 143 99 
@ 40 100 64 d 64 144 100 
A 41 101 65 e 65 145 101 
B 42 102 66 f 66 146 102 
C 43 103 67 g 67 147 103 
D 44 104 68 h 68 150 104 
E 45 105 69 l 69 151 105 
F 46 106 70 j 6A 152 106 
G 47 107 71 k 6B 153 107 
H 48 110 72 H, 1 6C 154 108 
I 49 111 73 m 6D 155 109 
J 4A 112 74 n 6E 156 110 
K 4B 113 78 0 6F 157 111. 
L 4C 114 76 p 70 160 112 
M 4D 115 77 q 71 161 113 
N 4k 116 78 r | 72 162 114 
O 4F 117 79 s 73 163 115 
P 50 120 80 t 74 164 116 
Q 51 121 81 u 75 165 117 
R 52 122 82 Vv 76 166 118 
S 53 123 83 Ww 77 167 119 
T 54 124 84 Xx 78 170 120 
U 55 125 85 y 79 171 121 
V 56 126 86 Z 7A 172 122 
W O7 127 87 { 7B 173 123 
Xx 58 130 88 | 7C 174 124 
4 59 131 89 } 7D 175 125 
Z 5A 132 90 7 TE 176 126 


B-2 Characters Set ASCII Collating Sequence 


Appendix C 
Data Types 


The data type refers to the way in which bits are grouped and interpreted. In 
reference to the processor instructions, the data type of an operand identifies 
the size of the cperand and the significance of the bits in the operand. Data 
types applicable to SORT and its associated VAX/VMS programs are: sepa- 
rated into three classes; character, binary, and decimal. These classes can be 
subdivided into data types of different sizes and formats such as; byte, word, 
longword, quadword, floating, double floating, character string, packed deci- 
mal string, and variable-length bit field. 


C.1 Byte 


A byte is 8 contiguous bits starting on an addressable byte boundary. The bits 
are numbered from the right 0 through 7: 


7 0 


——) » 


A byte is specified by its address A. When interpreted arithmetically, a byte is 
a twos complement integer with bits of increasing significance going 0 through 
6 and bit 7 the sign bit. The value of the integer is in the range -128 through 
127. For the purposes of addition, subtraction, and comparison, VAX-~11 in- 
structions also provide direct support for the interpretation of a byte as an 
unsigned integer with bits of increasing significance going 0 through 7. The 
value of the unsigned integer is in the range 0 through 255. 


C.2 Word 


A word is 2 contiguous bytes starting on an arbitrary byte boundary. The bits 
are numbered from the right 0 through 15: 


1 
3) 0 


ee 


A word is specified by its address A, the address of the byte containing bit 0. 
When interpreted arithmetically, a word is a twos complement integer with 
bits of increasing significance going 0 through 14 and bit 15 the sign bit. The 
value of the integer is in the range -32,768 through 32,767. For the purposes of 


addition, subtraction and comparison, VAX-11 instructions also provide di- 
rect support for the interpretation of a word as an unsigned integer with bits of 
increasing significance going 0 through 15. The value of the unsigned integer is 
in the range 0 through 65,635. 


C.3 Longword 


A longword is 4 contiguous bytes starting on an arbitrary byte boundary. The 
bits are numbered from the right 0 through 31: 


3 
1 0 


| | 


A longword is specified by its address A, the address of the type containing bit 
0. When interpreted arithmetically, a longword is a twos complement integer 
with bits of increasing significance going 0 through 30 and bit 31 the sign bit. 
The value of the integer is in the range —2,147,483,648 through 2,147,483,647. 
For the purposes of addition, subtraction, and comparison, VAX~11 instruc- 
tions also provide direct support for the interpretation of a longword as an 
unsigned integer with bits of increasing significance going 0 through 31. The 
value of the unsigned integer is in the range 0 through 4,294,967,295. 


Note that the longword format is different from the longword format defined 
by the PDP--11 FP-11. In that format, bits of increasing significance go from 
16 through 31 and 0 through 14. Bit 15 is the sign bit. Most DIGITAL software 
and in particular PDP-11 FORTRAN and COBOL use the VAX-11 longword 


format. 


C.4 Quadword 


A quadword is 8 contiguous bytes starting on an arbitrary byte boundary. The 
bits are numbered from the right 0 through 63: 


3. 
{ : 0 
‘A 
"“A+4 
6 3 
3 2 


A quadword is specified by its address A, the address of the byte containing 
bit 0. When interpreted arithmetically, a quadword is a twos complement 
integer with bits of increasing significance going 0 through 62 and bit 63 the 
sign bit. The value of the integer is in the range -2**63 to 2**63-1. The quad- 
word data type is not fully supported by VAX-11 instructions. 


Data Types 


C.5 Floating 


A floating datum is 4 contiguous bytes starting on an arbitrary byte boundary. 
The bits are labelled from the right 0 through 31. 


3 111 
1 654 76 0 


| fraction fraction | ‘A 


A floating datum is specified by its address A, the address of the byte contain- 
ing bit 0. The form of a floating datum is sign magnitude with bit 15 the sign 
bit, bits 14:7 an excess 128 binary exponent, and bits 6:0 and 31:16 a normal- 
ized 24-bit fraction with the redundant most significant fraction bit not repre- 
sented. Within the fraction, bits of increasing significance go from 16 through 
31 and 0 through 6. The 8—bit exponent field encodes the values 0 through 255. 
An exponent value of 0 together with a sign bit of 0, is taken to indicate that 
the floating datum has a value of 0. Exponent values of 1 through 255 indicate 
true binary exponents of -127 through +127. An exponent value of 0, together 
with a sign bit of 1, is taken as reserved. Floating point instructions processing 
a reserved operand take a reserved operand fault (See Chapter 4 and 6). The 
value of a floating datum is in the approximate range .29*10**-38 through 
1.7*10**38. The precision of a floating datum is approximately one part in 
2**23, that is, typically 7 decimal digits. 











C.6 Double Floating 


A double floating datum is 8 contiguous bytes starting on an arbitrary byte 
boundary. The bits are labelled from the right 0 through 63: 


3 111 
1 65 4 76 0 










fraction s fraction "A 
fraction | fraction "A+4 
6 44 — 3 
3 8 7 2 


A double floating datum is specified by its address A, the address of the byte 
containing bit 0. The form of a double floating datum is identical to a floating 
datum except for an additional 32 low significance fraction bits. Within the 
fraction, bits of increasing significance go 48 through 63, 32 through 47, 16 
through 31, and 0 through 6. The exponent conventions, and approximate 
range of values is the same for double floating as floating. The precision of a 
double floating datum is approximately one part in 2**55, that is, typically 16 
decimal digits. 
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C.7 Variable Length Bit Field 


C-4 


A variable bit field is 0 to 32 contiguous bits located arbitrarily with respect to 
byte boundaries. A variable bit field is specified by 3 attributes: the address A 
of a byte, a bit position P which is the starting location of the field with 
respect to bit 0 of the byte at A, and a size S of the field. The specification of a 
bit field is indicated by the following where the field is the shaded area. 





The position is in the range -2**31 through 2**31-1 and is conveniently 
viewed as a signed 29-bit offset and a 3-bit bit-within-byte (BWB) field: 


1 32 0 


| byte offset bwb | 





The sign extended 29-bit byte offset is added to the address A and the result- 
ing address specifies the byte in which the field begins. The 3-bit bit-within- 
byte field encodes the starting position (0 through 7). of the field within that 
byte. The VAX-11 field instructions provide direct support for the interpreta- 
tion of a field as a signed or unsigned integer. When interpreted as a signed 
integer, it is twos complement with bits of increasing significance going 0 
through S-2; bit S-1 is the sign bit. When interpreted as an unsigned integer, 
bits of increasing significance go from 0 to S-1. A field of size 0 has a value 
identically equal to 0. 


A variable bit field may be contained in 1 to 5 bytes. From a memory manage- 
ment point of view, only the minimum number of bytes necessary to contain 
the field is actually referenced. : 
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C.8 Character String 


A character string is a contiguous sequence of bytes in memory. A character 
string is specified by 2 attributes: the address A of the first byte of the string, 
and the length L of the string in bytes. Thus the format of a character string 
is: 


7 0 


The address of a string specifies the first character of a string. Thus "XYZ" is 
represented: 


“A+1 


‘A+2 





The length L of a string is in the range 0 through 65,535. 


C.9 Trailing Numeric String 


A trailing numeric string is a contiguous sequence of bytes in memory. The 
string is specified by 2 attributes: the address A of the first byte (most signifi- 
cant digit) of the string, and the length L of the string in bytes. 


All bytes of a trailing numeric string, except the least significant digit byte, 
must contain an ASCII decimal digit character (0-9). The representation for 
the high order digits is: 


ASCII 
digit decimal hex character 
0 48 30 0 
1 49 31 1 
2 50 32 2 
3 51 33 3 
4 52 34 4 
5 53 35 5 
6 54 36 6 
7 55 37 7 
8 56 38 8 
9 57 39 9 
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The highest addressed byte of a trailing numeric string represents an encoding 
of both the least significant digit and the sign of the numeric string. The VAX 
numeric string instructions support any encoding; however, there are 3 pre- 
ferred encodings used by DIGITAL software. These are (1) unsigned numeric 
in which there is no sign and the least significant digit contains an ASCII 
decimal digit character, (2) zoned numeric, and (3) overpunched numeric. 
Because the overpunch format has been used by compilers of many manufac- 
turers over many years, and because various card encodings are used, several 
variations in overpunch format have evolved. Typically, these alternate forms 
are accepted on input. The valid representations of the digit and sign in each 
of the later two formats is: 


Representation of Least Significant Digit and Sign 











Overpunch Format 


Zoned Numeric Format 
ASCII char 


ASCII 








digit decimal hex char decimal hex ‘norm alt. 
0 48 30 0 123 7B { [? 
1 49 31 1 65 41 A a 
2 50 32 2 66 42 B b 
3 51 33 3 67 43 C c 
4 52 34 4 68 44 D d 
5 53 35 5 69 45 E e 
6 54 36 6 70 46 F f 
7 55 37 7 71 47 G g 
8 56 38 8 72 48 H h 
9 57 39 9 73 49 I i 
-0 112 70 p 125 7D iis 
-1 113 71 q 74 4A J j 
-2 114 72 r- 715 4B K k 
-3 115 73 s 76 4C L l 
—4 116 74 t 77 4D M m 
-5 117 75 u 78 4K N n 
-6 118 76 Vv 79 4F O ) 
-7 119 77 Ww 80 50 P p 
-8 120 78 X 81 51 Q q 
-9 121 79 y 82 52 R r 





The length L of a trailing numeric string must be in the range 0 to 31 (0 to 31 
digits). The value of a 0 length string is identically 0. The address A of the 
string specifies the byte of the string containing the most significant digit. 
Digits of decreasing significance are assigned to increasing addresses. Thus 
"123" is represented: | 


Zoned Format or Unsigned Overpunch Format 
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and "-123" is represented: 


Zoned Format Overpunch Format 





C.10 Leading Separate Numeric String 


A leading separate numeric string is a contiguous sequence of bytes in mem- 
ory. A leading separate numeric string is specified by 2 attributes: the address 
A of the first byte (containing the sign character), and a length L, which is the 
length of the string in digits and NOT the length of the string in bytes. The 
number of bytes in a leading separate numeric string is L+1. 


The sign of a separate leading numeric string is stored in a separate byte. 
Valid sign bytes are: 


Sign decimal hex ASCII character 
+ 43 2B + 
+ 32 20 <blank> 
_ 45 2D - 


The preferred representation for "+" is ASCII "+". All subsequent bytes con- 
tain an ASCII digit character: 


digit decimal hex ASCII character 
0 48 30 0 
1 49 31 1 
2 50 32 2 
3 51 33 3 
4 52 34 4 
5 53 35 5 
6 54 36 6 
7 55 37 7 
8 56 38 8 
9 57 39 9 


The length L of a leading separate numeric string must be in the range 0 to 31 
(0 to 31 digits). The value of a 0 length string is identically 0. 
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The address A of the string specifies the byte of the string containing the sign. 
Digits of decreasing significance are assigned to bytes of increasing addresses. 
Thus "+123" is: | 


‘A+1 
“A+2 


‘A+3 





.C.11 Packed Decimal String 


A packed decimal string is a contiguous sequence of bytes in memory. A 
packed decimal string is specified by 2 attributes: the address A of the first 
byte of the string and a length L which is the number of digits in the string 
and NOT the length of the string in bytes. The bytes of a packed decimal 
string are divided into 2 4-bit fields (nibbles) which must contain decimal 
digits except the low nibble (bits 3:0) of the last (highest addressed) byte 
which must contain a sign. The representation for the digits and sign is: 


digit or sign decimal hex 

0 0 0 

1 1 1 

2 2 2 

3 3 3 

4 4 4 

5 5 5 

6 6 6 

7 7 7 

8 8 8 

9 9 9 

+ 10,12,14, or 15 A,C,E, or F 
- 11 or 13 B, or D 
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The preferred sign representation is 12 for "+" and 13 for "-". The length L is 
the number of digits in the packed decimal string (not counting the sign) and 
must be in the range 0 through 31. When the number of digits is odd, the 
digits and the sign fit in L/2 (integer part only) + 1 bytes. When the number of 
digits is even, it is required that an extra "0" digit appear in the high nibble 
(bits 7:4) of the first byte of the string. Again the length in bytes of the string 
is L/2 + 1. 


The address A of the string specifies the byte of the string containing the most 
significant digit in its high nibble. Digits of decreasing significance are as- 
signed to increasing byte addresses and from high nibble to low nibble within 
a byte. Thus "+123" has length 3 and is represented: 
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Appendix D 
Data Structures and Basic Concepts 


D.1 Data 


This Appendix provides beginning users with additional information regard- 
ing the following topics: 


e VAX-11 RMS data files, records, and structures 
e File specification parameters 


e Programming languages 


Files, Records, and Structures 


D.1.1 Data Hierarchy 


Four level data hierarchy (character, field, record, file) is shown in Figure D.1: 


Figure D.1: Data Hierarchy 
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A file is a collection of related information. For example, a file might contain a 
company’s personnel information (employee names, addresses, and job titles). 
Within this file, the information is divided into records. All the information on 
a single employee might constitute a single record. Each record in the person- 
nel file would be subdivided into discrete pieces of information known as 
fields. By specifying key fields (Keys) in a particular order, you can sort entire 
records into any order. Using VAX-11 SORT you can retrieve records in 
ascending or descending order by ordered key fields (that is, create sorted 
data files); and you can create sorted address files for random record retrieval 
by user programs. 


D.1.2 Record Types 


VAX-11 SORT processes three different types of records: Fixed, Variable, and 
Variable with fixed-length control (VFC). Figure D.2 summarizes these record 
types. 


Figure D.2: Record Types (fixed, variable, VFC) 
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D.1.3 VAX-11 RMS File Organizations 


1. Sequential Files (see Figure D.3) Sequential files may contain the follow- 
ing record types: 


a. Fixed Length Records 
b. Variable Length Records 
c. Variable with Fixed-length Control (VFC) Records 


The order of the records in a sequential file is determined by the order in 
which the records were originally written to the file. The first record in the 
file is the first record read; the second record next, and so on.Sequential 
files are the only files permitted for magnetic tape and unit record devices. 
They are also permitted for disk. 


2. Relative Files — Records may be any type (that is, fixed, variable, or VFC) 
as long as the maximum record length is specified. Each record is 
numbered 1 to n relative to the beginning of file (as shown in Figure D.4). 


A relative file consists of record areas (cells) that are identified by relative 
record numbers. The first record area in the file is record number 1, the 
second is 2, and so on. Empty or null records are permitted. Relative files 
can reside only on disk. 


Relative file considerations: 


e Most efficient random access in terms of speed and storage space over- 
head. 


e Addresses of records (relative record numbers) must be known to process 
file randomly. 


e Requires storage space to contain all record positions from record num- 
ber one to highest record number stored in file. 


e Records can span blocks, but cannot span buckets. 


e Can be write shared. 


3. Indexed Files — Contain one or more indices, as well as data records. 
Records can be of any type (that is, fixed, variable, or VFC) as long as the 
maximum record length is specified. To retrieve information, you ask for 
the proper record by primary or alternate key. The system looks up the 
key in the appropriate index and retrieves the record using the record 
pointer associated with the key. Indexed files can reside only on disk. 


The location of records in the indexed file organization is transparent to 
the program. RMS completely controls the placement of records in an 
indexed file. The presence of keys in the records of the file governs this 
placement. | 
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A key is a field present in every record of an indexed file. The location and 
length of this field are identical in all records. When creating an indexed 
file, the user decides which field or fields in the file’s records are to be a 
key. Selecting such fields indicates to RMS that the contents (that is, key 
value) of those fields in any particular record written to the file can be 
used by a program to identify that record for subsequent retrieval. 


At least one key must be defined for an indexed file: the primary key. 
Optionally, additional keys or alternate keys can be defined. An alternate 
key value can also be used as a means of identifying a record for retrieval. 


As programs write into an indexed file, RMS builds a tree-structured table 


_ known as an index. An index consists of a series of entries containing a key 


value copied from a record that a program wrote into the file. Stored with 
each key value is a pointer to the location in the file of the record from 
which the value was copied. RMS builds and maintains a separate index 
for each key defined for the file. Each index is stored in the file. Thus, 
every indexed file contains at least one index, the primary key index. 
Figure D.5 shows an RMS indexed file organization with a primary key. 
When alternate keys are defined, RMS builds and stores an additional 
index for each alternate key. 


Index file considerations: 
¢ Multi-key indexed sequential capability. 
e Most flexible in terms of how a record is accessed. 


e A record is addressed by the contents of a field in the record (the key 
field). 


e Records can be retrieved sequentially in a collated order by key field. 


e Requires the most storage overhead (that is, the RMS index tree 
structure). 


e Index records consist of block numbers, byte-in-block numbers and key. 


e Can be write shared. 


All VAX-11 RMS files have two additional blocks in the directory. These 
additional blocks contain information relating the type of RMS file and the 
record length. 
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Figure D.3: Sequential Files 
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Figure D.4: Relative Files 
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Figure D.5: Indexed Files 
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D.2 Input 


node-names:: 


and Output File Specification 


An input or output file specification uniquely identifies a file by indicating its 
physical location and a directory in which it is cataloged, as well as providing 
a unique filename for that particular file within the directory. However, it is 
not necessary to supply the physical location and directory for the file, since 
the system uses the defaults set up during the log-in procedure when these 
components are omitted from a file specification. 


This section is only a summary. For a full description of defaults, wild cards, 
logical names, and subdirectories, see the VAX/VMS Command Language 
User’s Guide. 


The format of a file specification representing a physical file or device is: 
device-name:CdirectoryjJfilename,file-typesfile-version 


Node-name:: The individual computer system (or node) name within a net- 
work consists of 1-6 alphanumeric characters. 


Example: BOSTON:: 


Device-name: The device name consists of three components: device type 
~ [controller] [unit-number]: 


The maximum length of the device type and controller specifi- 
cation is 15 characters. The maximum unit number is 65535. 
The default value for controller is A, and the default value for 
unit is 0. 


Physical device names are: 


Mnemonic Device 
CR Card Reader 
DB RP04, RPO5, RPO6 Disk 
DM RK0O6 Disk 
DR RMO03 Disk 
DX Floppy Disk 
LP Line Printer 
MB Mailbox 
MT TE16 Magnetic Tape 
NET Network Communication Device 
TT Interactive Terminal 
XM DMC-11 


Example: DB: is actually device name DBAO: by default. 


[directory] The directory name or names must be inclosed in either 
square brackets ({]) or angle brackets (<>). A directory with- 
out a directory name (for example, []) is not valid. The direc- 
tory types are: 


e A 1- to 9-alphanumeric character string 


e A two-part number in the format of a user identification 
code (UIC) 


D-6 Data Structures and Basic Concepts 


Filename. 


File type 


-File-version 


File type 


B2S 


CMD 
COM 





e As subdirectories, in the format of name.name.name where 
each name can consist of up to 9 alphanumberic characters; 
each name represents a diretory level. 


The file name is limited to nine ASCII characters. 


The file type is limited to three ASCII characters. Some com- 
monly used file types are: 


Contents 


Input source file for the PDP-11 BASIC-PLUS-2/VAX com- 
piler 

Compatibility mode indirect command file 

Command procedure file to be executed with the @ (Execute 
Procedure) command, or to be submitted for batch execution 
with the SUBMIT command | 

Input file containing source statements for the PDP-11 
COBOL-74/VAX compiler 

Input or output data file 

Output listing created by the DIFFERENCES command 
Directory file 
Output listing created by the DUMP command 
Executable program image 

Input file containing source statements for the VAX-11 
FORTRAN-IV-PLUS compiler 

Library file 

Listing file created by a language compiler or assembler; 
default input file type for PRINT and TYPE commands 
Batch job output file 

Compatibility mode listing file 

MACRO-11 source file 

Memory allocation map created by the linker 

VAX -11 MACRO source file 

Macro library 

Object file created by a language compiler or assembler 
Overlay description file 

Object module library 

Options file for input to the LINK command 

Symbol table file created by the linker 

Compatibility mode task image 


The file version number is automatically updated by the sys- 
tem each time the file is changed. Commands may optionally 
use a period to delimit the file version number, but the docu- 
mentation will use a semicolon. 


* indicates default file type for input files. Default file type for output files is whatever the 


input file type is. 
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D-8 


The following compilers produce native mode programs that can use VAX-11 
SORT: 


e VAX-11 FORTRAN IV-PLUS 
e VAX-11 MACRO 

e VAX-11 BLISS 

¢ VAX-11 COBOL-74 


VAX-11 FORTRAN IV-PLUS 


FORTRAN IV-PLUS is an especially complete version of the leading lan- 
guage for scientific and engineering computation. It is a high-performance 
superset of the American National Standard Institute’s (ANSI) 1966 FOR- 
TRAN. It also implements many of the anticipated features of the forthcom- 
ing ANSI standard. 


FORTRAN IV-PLUS supports character data types, an IF-THEN-ELSE 
statement, long variable names, and the standard CALL facility for calling 
system services. 


The FORTRAN IV-PLUS compiler first optimizes user source code, then 
translates it to take advantage of the VAX-11 instruction set, which can 
compile whole FORTRAN IV-PLUS statements into single instructions. An 
interactive symbolic debugger allows source-level debugging of FORTRAN 
IV-PLUS programs. 


VAX-11 MACRO 


The VAX-11 MACRO assembly language allows the programmer to write 
32-bit machine language instructions for special efficiency. The symbolic de- 
bugger can also be used with VAX-11 MACRO. 


VAX-11 BLISS 


BLISS is a medium level language designed for building system software; 
such as compilers, real-time processors, and utilities. 


VAX-11 COBOL-74 
The VAX-11 COBOL-74 language is based on the 1974 ANSI standard. 
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Subroutines (Cont.) 
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